npm - @tryty/easydc-js - Versions diffs - 1.1.0 → 1.2.0 - Mend

@tryty/easydc-js 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # easydc-js
-Bot Discord **super mudah** di atas [discord.js](https://discord.js.org). Kamu cukup menulis perintah dengan sintaks `$fungsi[argumen]` seperti aoi.js, tanpa harus mengurus event, embed, tombol, atau database secara manual.
+A **super easy** Discord Bot wrapper built on top of [discord.js](https://discord.js.org). You only need to write commands using the `$function[argument]` syntax, without having to manually manage events, embeds, buttons, or databases.
 ```js
 const { Bot } = require('easydc-js');
@@ -12,62 +12,63 @@ bot.command({ name: 'ping', code: '🏓 Pong! $ping ms' });
 bot.connect();
 ```
-Ketik `!ping` di Discord → bot menjawab `🏓 Pong! 42 ms`.
+Type `!ping` in Discord → the bot replies `🏓 Pong! 42 ms`.
-> **Catatan:** ini package independen, bukan bagian resmi dari discord.js maupun aoi.js. Package ini memakai discord.js di belakang layar.
+> **Note:** This is an independent package, not an official part of discord.js. This package uses discord.js under the hood.
 ---
-## Daftar isi
-1. [Instalasi](#1-instalasi)
-2. [Membuat bot di Discord](#2-membuat-bot-di-discord)
-3. [Bot pertama](#3-bot-pertama)
-4. [Cara kerja sintaks `$fungsi`](#4-cara-kerja-sintaks-fungsi)
-5. [Jenis handler](#5-jenis-handler)
-6. [Opsi Bot](#6-opsi-bot)
-7. [Variabel & database](#7-variabel--database)
-8. [Kondisi `$if`](#8-kondisi-if)
-9. [Embed, tombol, select menu](#9-embed-tombol-select-menu)
-10. [Fitur lanjutan: modal, autocomplete, menu klik-kanan, poll, thread, webhook](#10-fitur-lanjutan)
-11. [Eval (khusus owner)](#11-eval-khusus-owner)
-12. [Membuat fungsi sendiri](#12-membuat-fungsi-sendiri)
-13. [Memisah command ke banyak file](#13-memisah-command-ke-banyak-file)
-14. [Keamanan](#14-keamanan)
-15. [Pemecahan masalah](#15-pemecahan-masalah)
-16. [Daftar semua fungsi](#16-daftar-semua-fungsi)
+## Table of Contents
+1. [Installation](#1-installation)
+2. [Creating a Bot on Discord](#2-creating-a-bot-on-discord)
+3. [Your First Bot](#3-your-first-bot)
+4. [How the `$function` Syntax Works](#4-how-the-function-syntax-works)
+5. [Handler Types](#5-handler-types)
+6. [Bot Options](#6-bot-options)
+7. [Variables & Database](#7-variables--database)
+8. [The `$if` Condition](#8-the-if-condition)
+9. [Embeds, Buttons, Select Menus](#9-embeds-buttons-select-menus)
+10. [Advanced Features: Modals, Autocomplete, Right-Click Menus, Polls, Threads, Webhooks](#10-advanced-features)
+11. [Eval (Owner Only)](#11-eval-owner-only)
+12. [Database & Plugins (MongoDB)](#12-database--plugins-mongodb)
+13. [Creating Custom Functions](#13-creating-custom-functions)
+14. [Splitting Commands into Multiple Files](#14-splitting-commands-into-multiple-files)
+15. [Security](#15-security)
+16. [Troubleshooting](#16-troubleshooting)
+17. [List of All Functions](#17-list of-all-functions)
 ---
-## 1. Instalasi
+## 1. Installation
-Butuh **Node.js 18.17 atau lebih baru**.
+Requires **Node.js 18.17 or newer**.
 ```bash
 npm install easydc-js discord.js
 ```
-## 2. Membuat bot di Discord
+## 2. Creating a Bot on Discord
-1. Buka <https://discord.com/developers/applications> → **New Application**.
-2. Menu **Bot** → **Reset Token** → salin token. **Jangan dibagikan ke siapa pun.**
-3. Di halaman yang sama, aktifkan **Privileged Gateway Intents**:
-   - **Message Content Intent** (wajib agar command berawalan `!` terbaca)
-   - **Server Members Intent** (untuk event member masuk/keluar & info member)
-4. Menu **OAuth2 → URL Generator** → centang `bot` dan `applications.commands` → pilih izin yang dibutuhkan → buka URL hasilnya untuk mengundang bot.
+1. Open <https://discord.com/developers/applications> → **New Application**.
+2. Go to the **Bot** menu → **Reset Token** → copy the token. **Do not share it with anyone.**
+3. On the same page, enable **Privileged Gateway Intents**:
+   - **Message Content Intent** (required for commands starting with prefix `!` to be read)
+   - **Server Members Intent** (for member join/leave events & member info)
+4. Go to the **OAuth2 → URL Generator** menu → check `bot` and `applications.commands` → select the required permissions → open the generated URL to invite the bot.
-Simpan token di variabel lingkungan, jangan ditulis di kode:
+Store the token in environment variables, do not write it directly in your code:
 ```bash
 # Linux / macOS
-TOKEN="token_kamu" node index.js
+TOKEN="your_token" node index.js
 # Windows PowerShell
-$env:TOKEN="token_kamu"; node index.js
+$env:TOKEN="your_token"; node index.js
 ```
-## 3. Bot pertama
+## 3. Your First Bot
-Buat `index.js`:
+Create `index.js`:
 ```js
 const { Bot } = require('easydc-js');
@@ -78,721 +79,835 @@ const bot = new Bot({
   timezone: 'Asia/Jakarta',
 });
-bot.variables({ uang: 100 });
+bot.variables({ money: 100 });
 bot.command({
-  name: 'uang',
-  code: '💰 $username punya $getUserVar[uang] koin',
+  name: 'money',
+  code: '💰 $username has $getUserVar[money] coins',
 });
 bot.command({
-  name: 'kerja',
+  name: 'work',
   code: `
-$cooldown[1m;Istirahat dulu, tunggu %time%.]
-$setUserVar[uang;$math[$getUserVar[uang]+25]]
-Kamu dapat 25 koin! Total: $getUserVar[uang]
+$cooldown[1m;Take a rest first, please wait %time%.]
+$setUserVar[money;$math[$getUserVar[money]+25]]
+You got 25 coins! Total: $getUserVar[money]
 `,
 });
 bot.connect();
 ```
-Contoh lengkap ada di [`examples/basic.js`](examples/basic.js).
+A complete example can be found in [`examples/basic.js`](examples/basic.js).
-## 4. Cara kerja sintaks `$fungsi`
+## 4. How the `$function` Syntax Works
 ```
-$namaFungsi[argumen1;argumen2;...]
+$functionName[argument1;argument2;...]
 ```
-- Argumen dipisah dengan **titik koma** `;`.
-- Fungsi boleh **bersarang**: `$toUpperCase[$username]`, `$math[$getUserVar[uang]*2]`.
-- Nama fungsi **tidak peka huruf besar/kecil** (`$Username` = `$username`).
-- Fungsi yang tidak butuh argumen ditulis tanpa kurung: `$ping`, `$serverName`.
-- Hasil akhir seluruh teks (setelah semua `$fungsi` dijalankan) dikirim sebagai jawaban bot.
-- Teks yang panjangnya lebih dari 2000 karakter otomatis dipecah jadi beberapa pesan.
+- Arguments are separated by a **semicolon** `;`.
+- Functions can be **nested**: `$toUpperCase[$username]`, `$math[$getUserVar[money]*2]`.
+- Function names are **case-insensitive** (`$Username` = `$username`).
+- Functions that do not require arguments are written without parentheses: `$ping`, `$serverName`.
+- The final result of the entire text (after all `$functions` are executed) is sent as the bot's reply.
+- Texts exceeding 2000 characters are automatically split into multiple messages.
-### Menulis karakter khusus
+### Writing Special Characters
-Untuk menulis karakter `$ [ ] ;` sebagai teks biasa, beri backslash di depannya:
+To write `$ [ ] ;` characters as literal text, escape them with a backslash:
-| Tulis | Hasil |
+| Write | Result |
 |---|---|
-| `\$ping` | `$ping` (bukan dijalankan) |
+| `\$ping` | `$ping` (will not be executed) |
 | `\[` `\]` | `[` `]` |
-| `\;` | `;` (tidak memisah argumen) |
-| `\\` | `\` |
+| `\;` | `;` (will not separate arguments) |
+| `\` | `\` |
-Atau pakai fungsi `$semicolon`, `$leftBracket`, `$rightBracket`, `$dollar`.
-Tanda `$` yang diikuti angka atau spasi (misal `harga $5`) otomatis dianggap teks biasa.
+Alternatively, use the functions `$semicolon`, `$leftBracket`, `$rightBracket`, `$dollar`.
+A `$` sign followed by a number or space (e.g., `price $5`) is automatically treated as plain text.
-> Di dalam template string JavaScript (tanda `` ` ``), backslash perlu **digandakan**: `` `\\$ping` ``. Jika tidak mau repot, pakai `$dollar`.
+> Inside JavaScript template strings (backticks `` ` ``), backslashes need to be **doubled**: `` `\$ping` ``. If you want to avoid this, use `$dollar`.
-### Kode dicek sebelum bot menyala
+### Code Validation Before Bot Starts
-Saat `bot.connect()` dipanggil, **semua kode diperiksa dulu**. Kalau ada fungsi salah ketik, jumlah argumen salah, atau `$if` tanpa `$endif`, bot **tidak login** dan kamu mendapat daftar lengkap masalahnya, contoh:
+When `bot.connect()` is called, **all code is validated first**. If there is a misspelled function, wrong number of arguments, or an `$if` without an `$endif`, the bot **will not log in** and you will get a full list of issues, for example:
 ```
-Ditemukan 2 masalah pada kode:
- - command "ban": Fungsi $bann tidak dikenal (baris 3, kolom 1)
- - command "cek": $if tidak ditutup, tambahkan $endif (baris 1, kolom 1)
+Found 2 issues in the code:
+ - command "ban": Unknown function $bann (line 3, column 1)
+ - command "check": $if is not closed, add $endif (line 1, column 1)
 ```
-## 5. Jenis handler
+## 5. Handler Types
-### Command prefix
+### Prefix Commands
 ```js
-bot.command({ name: 'sapa', aliases: ['hai', 'halo'], code: 'Halo $username!' });
+bot.command({ name: 'greet', aliases: ['hi', 'hello'], code: 'Hello $username!' });
 ```
-Argumen setelah nama command: `$message` (semua), `$message[1]` (kata ke-1), `$argsCount`.
+Arguments after the command name: `$message` (all), `$message[1]` (1st word), `$argsCount`.
-### Slash command
+### Slash Commands
 ```js
 bot.slashCommand({
-  name: 'halo',                       // huruf kecil, tanpa spasi
-  description: 'Menyapa seseorang',
+  name: 'hello',                       // lowercase, no spaces
+  description: 'Greets someone',
   options: [
-    { name: 'nama', description: 'Nama', type: 'string', required: true },
-    { name: 'umur', description: 'Umur', type: 'integer', minValue: 1 },
+    { name: 'name', description: 'Name', type: 'string', required: true },
+    { name: 'age', description: 'Age', type: 'integer', minValue: 1 },
   ],
-  code: 'Halo, $option[nama]!',
+  code: 'Hello, $option[name]!',
 });
 ```
-Tipe opsi: `string integer boolean user channel role mentionable number attachment`.
-Slash command didaftarkan otomatis saat bot siap. Untuk uji coba cepat, isi `slashGuild: 'ID_SERVER'` (muncul seketika; kalau global bisa butuh waktu).
-Jika proses lebih dari 3 detik, taruh `$defer` di awal kode.
+Option types: `string integer boolean user channel role mentionable number attachment`.
+Slash commands are automatically registered when the bot is ready. For fast testing, set `slashGuild: 'GUILD_ID'` (appears instantly; global registration can take time).
+If the process takes longer than 3 seconds, put `$defer` at the top of the code.
-### Tombol & select menu
+### Buttons & Select Menus
 ```js
 bot.command({
-  name: 'tombol',
-  code: '$addButton[Klik;primary;klik_1]$addButton[Web;link;https://example.com]Pilih:',
+  name: 'button',
+  code: '$addButton[Click;primary;click_1]$addButton[Web;link;https://example.com]Choose:',
 });
-bot.button({ customId: 'klik_*', code: '$ephemeral Kamu menekan `$customID`' });   // * = wildcard
+bot.button({ customId: 'click_*', code: '$ephemeral You pressed `$customID`' });   // * = wildcard
 bot.command({
   name: 'menu',
-  code: `Pilih buah:
-$addSelectMenu[buah;Pilih...]
-$addSelectOption[Apel;apel;Buah merah]
-$addSelectOption[Jeruk;jeruk]`,
+  code: `Choose a fruit:
+$addSelectMenu[fruit;Choose...]
+$addSelectOption[Apple;apple;Red fruit]
+$addSelectOption[Orange;orange]`,
 });
-bot.select({ customId: 'buah', code: 'Kamu memilih: $interactionValues' });
+bot.select({ customId: 'fruit', code: 'You chose: $interactionValues' });
 ```
-Gunakan `$update` agar tombol/select mengubah pesan aslinya (bukan mengirim pesan baru).
+Use `$update` so that buttons/selects edit the original message instead of sending a new one.
-### Event
+### Events
-| Pendek | Dijalankan saat |
+| Short form | Executed when |
 |---|---|
-| `bot.onReady(code)` | bot siap |
-| `bot.onMemberJoin(code)` | member masuk server |
-| `bot.onMemberLeave(code)` | member keluar |
-| `bot.onMessageDelete(code)` | pesan dihapus |
-| `bot.onMessageUpdate(code)` | pesan diedit |
-| `bot.onReactionAdd(code)` / `onReactionRemove` | reaksi ditambah / dihapus |
-| `bot.onGuildJoin(code)` / `onGuildLeave` | bot masuk / keluar server |
-| `bot.onMessage(code)` | setiap pesan yang **bukan** command |
-| `bot.onMemberBan(code)` / `onMemberUnban` | user di-ban / ban dicabut (`$targetID`, `$targetName`) |
-| `bot.onChannelCreate(code)` / `onChannelDelete` | channel dibuat / dihapus (`$targetName`) |
-| `bot.onRoleCreate(code)` / `onRoleDelete` | role dibuat / dihapus (`$targetName`) |
-| `bot.onThreadCreate(code)` | thread baru (jawaban dikirim ke thread itu) |
-| `bot.onVoiceJoin(code)` / `onVoiceLeave` | member masuk / keluar voice (`$targetName` = nama voice). Pindah channel memicu keduanya |
-Secara bawaan jawaban dikirim ke channel sistem server. Pilih channel lain dengan bentuk objek:
+| `bot.onReady(code)` | bot is ready |
+| `bot.onMemberJoin(code)` | member joins the server |
+| `bot.onMemberLeave(code)` | member leaves |
+| `bot.onMessageDelete(code)` | message is deleted |
+| `bot.onMessageUpdate(code)` | message is edited |
+| `bot.onReactionAdd(code)` / `onReactionRemove` | reaction is added / removed |
+| `bot.onGuildJoin(code)` / `onGuildLeave` | bot joins / leaves a server |
+| `bot.onMessage(code)` | every message that is **not** a command |
+| `bot.onMemberBan(code)` / `onMemberUnban` | user is banned / ban lifted (`$targetID`, `$targetName`) |
+| `bot.onChannelCreate(code)` / `onChannelDelete` | channel is created / deleted (`$targetName`) |
+| `bot.onRoleCreate(code)` / `onRoleDelete` | role is created / deleted (`$targetName`) |
+| `bot.onThreadCreate(code)` | new thread (reply is sent to that thread) |
+| `bot.onVoiceJoin(code)` / `onVoiceLeave` | member joins / leaves voice (`$targetName` = voice name). Changing channels triggers both |
+By default, replies are sent to the system channel of the server. Choose another channel using an object format:
 ```js
-bot.onMemberJoin({ channel: 'ID_CHANNEL', code: 'Selamat datang $mention! Kita sekarang $memberCount orang.' });
+bot.onMemberJoin({ channel: 'CHANNEL_ID', code: 'Welcome $mention! We are now $memberCount people.' });
 ```
-## 6. Opsi Bot
+## 6. Bot Options
 ```js
 new Bot({
-  token: 'WAJIB',
-  prefix: '!',                  // atau ['!', '?']
-  mentionPrefix: true,          // @bot command juga bisa
-  ignoreBots: true,             // abaikan pesan dari bot lain
-  owners: ['ID_KAMU'],          // untuk $onlyOwner dan $isOwner
-  timezone: 'Asia/Jakarta',     // untuk $date
+  token: 'REQUIRED',
+  prefix: '!',                  // or ['!', '?']
+  mentionPrefix: true,          // @bot command works too
+  ignoreBots: true,             // ignore messages from other bots
+  owners: ['YOUR_ID'],          // for $onlyOwner and $isOwner
+  timezone: 'Asia/Jakarta',     // for $date
   intents: 'default',           // 'default' | 'all' | ['Guilds', ...]
-  status: { text: 'dengan kode', type: 'Playing', status: 'online' },
-  slashGuild: null,             // ID server untuk slash cepat (null = global)
-  syncSlash: true,              // daftarkan slash otomatis
-  database: { path: './easydc-data.json' },   // atau { memory: true }
-  messages: { cooldown: '⏳ Tunggu %time%.', error: '❌ Terjadi kesalahan.' },
-  debug: false,                 // true = tampilkan penyebab error di chat (hanya saat pengembangan!)
-  onError: (err, ctx) => {},    // tangani error sendiri
+  status: { text: 'with code', type: 'Playing', status: 'online' },
+  slashGuild: null,             // server ID for fast slash deployment (null = global)
+  syncSlash: true,              // auto register slash commands
+  database: { path: './easydc-data.json' },   // or { memory: true }
+  messages: { cooldown: '⏳ Wait %time%.', error: '❌ An error occurred.' },
+  debug: false,                 // true = show error causes in chat (development only!)
+  onError: (err, ctx) => {},    // handle errors manually
 });
 ```
-Intent bawaan: `Guilds, GuildMessages, MessageContent, GuildMembers, GuildMessageReactions, DirectMessages, GuildModeration, GuildVoiceStates`.
+Default intents: `Guilds, GuildMessages, MessageContent, GuildMembers, GuildMessageReactions, DirectMessages, GuildModeration, GuildVoiceStates`.
-Opsi tambahan: `eval: false` (nyalakan `$eval` / `$jsEval`, lihat [bagian 11](#11-eval-khusus-owner)).
+Additional option: `eval: false` (turns on `$eval` / `$jsEval`, see [section 11](#11-eval-owner-only)).
-## 7. Variabel & database
+## 7. Variables & Database
-Variabel disimpan permanen di file JSON (`easydc-data.json`). Deklarasikan dulu dengan nilai awal:
+Variables are permanently stored in a JSON file (`easydc-data.json`). Declare them first with default values:
 ```js
-bot.variables({ uang: 0, bio: 'Belum diisi' });
+bot.variables({ money: 0, bio: 'Not filled yet' });
 ```
-| Fungsi | Cakupan |
+| Function | Scope |
 |---|---|
-| `$getUserVar[nama;userID?]` `$setUserVar[nama;nilai;userID?]` `$resetUserVar` | per user |
+| `$getUserVar[name;userID?]` `$setUserVar[name;value;userID?]` `$resetUserVar` | per user |
 | `$getServerVar` `$setServerVar` `$resetServerVar` | per server |
 | `$getChannelVar` `$setChannelVar` `$resetChannelVar` | per channel |
-| `$getGlobalVar` `$setGlobalVar` `$resetGlobalVar` | satu untuk semua |
+| `$getGlobalVar` `$setGlobalVar` `$resetGlobalVar` | one for everyone |
-Semua nilai tersimpan sebagai **teks**. Gunakan `$math[...]` untuk berhitung.
-Variabel sementara selama satu command: `$let[nama;nilai]` dan `$get[nama]`.
+All values are stored as **strings**. Use `$math[...]` for calculations.
+Temporary variables during a single command execution: `$let[name;value]` and `$get[name]`.
-- Berkas database ditulis secara aman dan otomatis. Jika file rusak, ia **dicadangkan** (`*.corrupt-<waktu>`) dan bot mulai dari kosong, bukan crash.
-- Untuk bot besar (ribuan user aktif) pertimbangkan database sungguhan; `Database` bawaan cocok untuk bot kecil sampai menengah.
-- **Satu file database hanya boleh dipakai satu proses bot.**
+- To use MongoDB, see [section 12](#12-database--plugins-mongodb).
+- The database file is written safely and automatically. If the file is corrupted, it is **backed up** (`*.corrupt-<timestamp>`) and the bot starts fresh instead of crashing.
+- For large bots (thousands of active users), consider using a real database; the built-in `Database` is suitable for small to medium bots.
+- **A single database file must only be used by one bot process.**
-## 8. Kondisi `$if`
+## 8. The `$if` Condition
 ```
-$if[kondisi]
+$if[condition]
   ...
-$elseif[kondisi]
+$elseif[condition]
   ...
 $else
   ...
 $endif
 ```
-Operator: `==  !=  >  <  >=  <=`, digabung dengan `&&` (dan) / `||` (atau). Tanpa tanda kurung.
-Jika kedua sisi angka, dibandingkan sebagai angka (`10>9` benar); selain itu sebagai teks.
+Operators: `==  !=  >  <  >=  <=`, combined with `&&` (and) / `||` (or). No parentheses required.
+If both sides are numbers, they are compared numerically (`10>9` is true); otherwise, they are compared as text.
 ```
-$if[$getUserVar[uang]>=100&&$isAdmin==true]
-Kaya dan admin
-$elseif[$getUserVar[uang]>=100]
-Kaya
+$if[$getUserVar[money]>=100&&$isAdmin==true]
+Rich and admin
+$elseif[$getUserVar[money]>=100]
+Rich
 $else
-Miskin
+Poor
 $endif
 ```
-**Aman dari injeksi:** nilai dinamis seperti `$message` tidak bisa dipakai pengguna untuk menyisipkan operator `&&`, `||`, dan sejenisnya ke dalam kondisi. Isi pesan pengguna selalu diperlakukan sebagai teks biasa.
+**Injection safe:** dynamic values like `$message` cannot be used by users to inject operators like `&&`, `||`, and similar into the condition. The user content is always treated as a plain text string.
-Pembatas lain: `$onlyIf[kondisi;pesan?]`, `$stop[pesan?]`, `$onlyPerms`, `$onlyAdmin`, `$onlyOwner`, `$onlyForIDs`, `$onlyInServer`, `$argsCheck`, `$cooldown`.
+Other constraints: `$onlyIf[condition;message?]`, `$stop[message?]`, `$onlyPerms`, `$onlyAdmin`, `$onlyOwner`, `$onlyForIDs`, `$onlyInServer`, `$argsCheck`, `$cooldown`.
-## 9. Embed, tombol, select menu
+## 9. Embeds, Buttons, Select Menus
 ```js
 bot.command({
   name: 'info',
   code: `
 $title[Info $serverName]
-$description[Server ini punya $memberCount member.]
+$description[This server has $memberCount members.]
 $color[#5865F2]
 $thumbnail[$serverIcon]
-$addField[Dibuat;$discordTime[$serverCreatedAt;D];true]
+$addField[Created;$discordTime[$serverCreatedAt;D];true]
 $addField[Ping;$ping ms;true]
-$footer[Diminta oleh $username]
+$footer[Requested by $username]
 $addTimestamp
 `,
 });
 ```
-- Embed pertama dibuat otomatis; `$newEmbed` memulai embed berikutnya (maksimal 10).
-- Warna: `#RRGGBB`, nama (`red green blue yellow orange purple pink white black grey blurple`), atau `random`.
-- Tombol: maksimal 5 per baris, 5 baris per pesan. Baris baru dibuat otomatis, atau paksa dengan `$newRow`.
-- Panjang teks dicek sesuai batas Discord, dengan pesan error yang jelas jika terlampaui.
+- The first embed is created automatically; `$newEmbed` starts the next embed (maximum 10).
+- Colors: `#RRGGBB`, names (`red green blue yellow orange purple pink white black grey blurple`), or `random`.
+- Buttons: maximum 5 per row, 5 rows per message. New rows are made automatically, or can be forced using `$newRow`.
+- Text length is validated against Discord limits, providing clear error messages if exceeded.
-## 10. Fitur lanjutan
+## 10. Advanced Features
-### Modal (form pop-up)
+### Modals (Pop-up Forms)
-Modal harus menjadi respons **pertama** dari slash command, tombol, atau select menu (jangan pakai `$defer` sebelumnya; teks lain di command itu diabaikan).
+Modals must be the **first** response to a slash command, button, or select menu interaction (do not use `$defer` beforehand; other texts in that command will be ignored).
 ```js
 bot.slashCommand({
-  name: 'lapor',
-  description: 'Kirim laporan',
+  name: 'report',
+  description: 'Send a report',
   code: `
-$addModal[lapor_form;Form Laporan]
-$addTextInput[judul;Judul;short;Ringkas saja;true;3;50]
-$addTextInput[isi;Isi laporan;paragraph]
+$addModal[report_form;Report Form]
+$addTextInput[title;Title;short;Keep it brief;true;3;50]
+$addTextInput[content;Report content;paragraph]
 `,
 });
 bot.modal({
-  customId: 'lapor_form',          // boleh wildcard: 'lapor_*'
-  code: '$ephemeral Terima kasih! Judul: $modalValue[judul] | Isi: $modalValue[isi]',
+  customId: 'report_form',          // card wildcards allowed: 'report_*'
+  code: '$ephemeral Thank you! Title: $modalValue[title] | Content: $modalValue[content]',
 });
 ```
-Maksimal 5 kolom per modal. `$addTextInput[customID;label;gaya?;placeholder?;wajib?;min?;max?;nilaiAwal?]`, gaya `short` atau `paragraph`.
+Maximum 5 inputs per modal. `$addTextInput[customID;label;style?;placeholder?;required?;min?;max?;initialValue?]`, styles are `short` or `paragraph`.
-### Autocomplete (pilihan dinamis di slash command)
+### Autocomplete (Dynamic Choices in Slash Commands)
 ```js
 bot.slashCommand({
-  name: 'buah',
-  description: 'Pilih buah',
-  options: [{ name: 'nama', description: 'Nama buah', autocomplete: true }],   // tidak bisa bersama "choices"
-  code: 'Kamu memilih $option[nama]',
+  name: 'fruit',
+  description: 'Select a fruit',
+  options: [{ name: 'name', description: 'Fruit name', autocomplete: true }],   // cannot be used together with "choices"
+  code: 'You selected $option[name]',
 });
 bot.autocomplete({
-  command: 'buah',
-  option: 'nama',            // kosongkan untuk semua opsi autocomplete di command itu
+  command: 'fruit',
+  option: 'name',            // leave empty for all autocomplete options in that command
   code: `
-$if[$checkContains[apel;$toLowerCase[$focusedValue]]==true]$addChoice[Apel;apel]$endif
-$addChoice[Jeruk;jeruk]
-$addChoice[Mangga;mangga]
+$if[$checkContains[apple;$toLowerCase[$focusedValue]]==true]$addChoice[Apple;apple]$endif
+$addChoice[Orange;orange]
+$addChoice[Mango;mangga]
 `,
 });
 ```
-`$focusedValue` = teks yang sedang diketik. `$addChoice[nama;nilai?]` maksimal 25. Untuk opsi `integer`/`number`, nilai pilihan harus angka. Discord memberi waktu 3 detik, jadi jangan pakai `$wait`.
+`$focusedValue` = the text currently typed by the user. `$addChoice[name;value?]` max 25 choices. For `integer`/`number` options, the choice value must be a number. Discord gives 3 seconds to respond, so do not use `$wait`.
-### Menu klik-kanan (context menu)
+### Right-Click Menus (Context Menus)
 ```js
-bot.contextMenu({ name: 'Lihat Profil', menu: 'user', code: '$ephemeral Profil: $targetName (ID $targetID)' });
-bot.contextMenu({ name: 'Laporkan', menu: 'message', code: '$ephemeral Pesan "$targetContent" dari $targetName dilaporkan.' });
+bot.contextMenu({ name: 'View Profile', menu: 'user', code: '$ephemeral Profile: $targetName (ID $targetID)' });
+bot.contextMenu({ name: 'Report Message', menu: 'message', code: '$ephemeral Message "$targetContent" from $targetName reported.' });
 ```
-Muncul di menu *Apps* ketika pengguna klik kanan user atau pesan. Didaftarkan otomatis bersama slash command.
+Appears under the *Apps* menu when a user right-clicks a user or a message. Automatically registered alongside slash commands.
-### Select menu user / role / channel
+### User / Role / Channel Select Menus
 ```
-$addUserSelect[pilih_user;Pilih user;1;3]
-$addRoleSelect[pilih_role]
-$addMentionableSelect[pilih_apa_saja]
-$addChannelSelect[pilih_channel;Pilih channel;;;text,voice]
+$addUserSelect[select_user;Select user;1;3]
+$addRoleSelect[select_role]
+$addMentionableSelect[select_anything]
+$addChannelSelect[select_channel;Select channel;;;text,voice]
 ```
-Daftarkan handler dengan `bot.select({ customId: 'pilih_user', code: 'Dipilih: $interactionValues' })`. Nilainya berupa ID, dipisah koma.
+Register handlers via `bot.select({ customId: 'select_user', code: 'Selected: $interactionValues' })`. Values are comma-separated IDs.
-### Lampiran, polling, webhook
+### Attachments, Polls, Webhooks
 ```
-$addAttachment[https://example.com/gambar.png;gambar.png]
-$addTextFile[catatan.txt;isi file teks buatan sendiri]
-$poll[Makan apa?;24;false;Nasi;Mie;Roti]
-$sendWebhook[https://discord.com/api/webhooks/ID/TOKEN;Halo!;Nama Bot;https://example.com/avatar.png]
+$addAttachment[https://example.com/image.png;image.png]
+$addTextFile[notes.txt;custom text file content created on the fly]
+$poll[What to eat?;24;false;Chips;Noodles;Bread]
+$sendWebhook[https://discord.com/api/webhooks/ID/TOKEN;Hello!;Bot Name;https://example.com/avatar.png]
 ```
-Lampiran hanya dari URL `http(s)` atau teks buatan sendiri (bot tidak membaca file dari disk). `$poll[pertanyaan;jam;multi;opsi...]` butuh 2-10 opsi.
+Attachments only accept `http(s)` URLs or custom on-the-fly text strings (the bot does not read files from disk). `$poll[question;hours;multi;options...]` requires 2-10 options.
-### Thread, forum, dan manajemen server
+### Threads, Forums, and Guild Management
 ```
-$createThread[Diskusi;$messageID;1440]       -> mengembalikan ID thread
-$createForumPost[ID_FORUM;Judul;Isi]
-$unban[ID;alasan]            $isBanned[ID]          $banCount
-$createChannel[info;text;ID_KATEGORI;Topik]   $lockChannel   $unlockChannel
+$createThread[Discussion;$messageID;1440]       -> returns thread ID
+$createForumPost[FORUM_ID;Title;Content]
+$unban[ID;reason]            $isBanned[ID]          $banCount
+$createChannel[info;text;CATEGORY_ID;Topic]   $lockChannel   $unlockChannel
 $createRole[VIP;#ff0000;true]                 $createInvite[;3600;10]
-$createEvent[Nobar;MULAI_MS;SELESAI_MS;Voice 1;Deskripsi]
+$createEvent[WatchParty;START_MS;END_MS;Voice 1;Description]
 ```
-Fungsi manajemen memakai **izin bot**, jadi lindungi dengan `$onlyPerms[...]` seperti di bagian [Keamanan](#14-keamanan). Daftar lengkapnya ada di bagian [Daftar semua fungsi](#16-daftar-semua-fungsi).
+Management functions use **bot permissions**, so make sure to protect them with `$onlyPerms[...]` as explained in the [Security](#15-security) section. The full list is located in the [List of All Functions](#17-list-of-all-functions) section.
 ---
-## 11. Eval (khusus owner)
+## 11. Eval (Owner Only)
-Eval menjalankan kode yang diketik saat bot berjalan, berguna untuk debugging. Ada dua jenis:
+Eval executes code inputted dynamically while the bot is running, which is useful for debugging. There are two types:
-| Fungsi | Bahasa kode yang dijalankan |
+| Function | Code Language Executed |
 |---|---|
-| `$eval[kode]` | kode versi port, yaitu sintaks `$fungsi` package ini |
-| `$jsEval[kode]` | JavaScript / **discord.js asli** |
+| `$eval[code]` | Wrapper-version code, which uses this package's `$function` syntax |
+| `$jsEval[code]` | JavaScript / **native discord.js** |
-Di `$jsEval` tersedia variabel: `ctx` `client` `bot` `guild` `channel` `message` `user` `member` `interaction` `discord` (modul discord.js) `db` `require`. Ekspresi tunggal langsung dikembalikan hasilnya; untuk beberapa pernyataan, tulis `return`. Boleh memakai `await`.
+In `$jsEval`, the following variables are available: `ctx` `client` `bot` `guild` `channel` `message` `user` `member` `interaction` `discord` (discord.js module) `db` `require`. A single expression is directly returned; for multiple statements, use `return`. Supports `await`.
-### Cara pakai paling mudah
+### Easiest Way to Use
 ```js
 const bot = new Bot({
   token: process.env.TOKEN,
-  owners: ['ID_DISCORD_KAMU'],
-  eval: true,                // eval MATI kecuali dinyalakan di sini
+  owners: ['YOUR_DISCORD_ID'],
+  eval: true,                // eval is DISABLED unless turned on here
 });
-bot.evalCommand();           // memasang command "eval" (nama bisa diganti: { name: 'e', aliases: ['ev'] })
+bot.evalCommand();           // mounts the "eval" command (name can be changed: { name: 'e', aliases: ['ev'] })
 ```
-Lalu di Discord:
+Then in Discord:
 ```
-!eval $math[6*7]                         -> kode versi port
-!eval Halo $username dari $serverName
-!eval js client.guilds.cache.size        -> discord.js asli
+!eval $math[6*7]                         -> wrapper syntax version
+!eval Hello $username from $serverName
+!eval js client.guilds.cache.size        -> native discord.js
 !eval js guild.members.cache.filter(m => m.user.bot).size
 !eval js const g = await client.guilds.fetch(guild.id);
 return g.memberCount;
 ```
-Hasil dikirim dalam blok kode (maksimal ±1800 karakter), error ditampilkan sebagai `❌ ...`, dan **token otomatis disensor** dari hasil.
+Results are sent inside a code block (max ±1800 characters), errors are displayed as `❌ ...`, and **tokens are automatically censored** from the output.
-Bisa juga dipakai di command buatan sendiri: `$eval[$message]` dan `$jsEval[$message]`. Gunakan `$messageFrom[2]` untuk mengambil semua teks mulai kata ke-2 (spasi dan baris baru terjaga).
+Can also be used in custom commands: `$eval[$message]` and `$jsEval[$message]`. Use `$messageFrom[2]` to get all text starting from the 2nd word (preserving spaces and newlines).
-### ⚠️ Peringatan keamanan
+### ⚠️ Security Warnings
-- **`$jsEval` memberi akses PENUH** ke bot dan mesin tempat bot berjalan: membaca file, variabel lingkungan, mengirim data keluar, bahkan mematikan proses. Eval hanya berjalan bila `eval: true` **dan** pengirim ada di `owners`; selain itu langsung ditolak.
-- Isi `owners` hanya dengan ID **Anda sendiri**. Jangan beri akses kepada orang lain, termasuk "admin kepercayaan".
-- Jika akun Discord owner dibajak, penyerang bisa mengambil alih server hosting. Aktifkan 2FA.
-- Matikan `eval` (hapus `eval: true`) di bot produksi yang tidak membutuhkannya.
-- Sensor token hanya pencegah kecelakaan, bukan pengaman: kode JS tetap bisa membaca token dan mengirimnya ke tempat lain.
-- `$eval` bersarang dibatasi 3 tingkat. Perulangan tak berujung (`while(true){}`) di `$jsEval` tidak bisa dihentikan, dan akan membekukan bot sampai di-restart.
+- **`$jsEval` grants FULL access** to the bot and the machine it runs on: reading files, environment variables, sending data out, and even terminating the process. Eval only runs if `eval: true` **and** the sender is listed in `owners`; otherwise, it is rejected immediately.
+- Only include **YOUR OWN** ID in `owners`. Do not grant access to anyone else, including "trusted admins".
+- If the owner's Discord account is compromised, the attacker can take over your hosting server. Enable 2FA.
+- Disable `eval` (remove `eval: true`) in production bots that do not need it.
+- Token censoring is just an accidental leaks prevention tool, not a foolproof security measure: JS code can still read tokens and send them elsewhere.
+- Nested `$eval` calls are limited to 3 levels. Infinite loops (`while(true){}`) in `$jsEval` cannot be stopped and will freeze the bot until it is restarted.
 ---
-## 12. Membuat fungsi sendiri
+## 12. Database & Plugins (MongoDB)
+By default, variable data is saved in the `easydc-data.json` file. For production bots (where data shouldn't be lost when a hosting provider deletes files, or when running across multiple servers), use **MongoDB** via a plugin.
+### Install the MongoDB Plugin
+```bash
+npm install easydc-js discord.js mongodb
+```
+```js
+const { Bot } = require('easydc-js');
+const { mongodb } = require('easydc-js/mongodb');
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!' });
+bot.use(mongodb({
+  uri: process.env.MONGO_URI,     // e.g., mongodb+srv://user:pass@cluster0.xxxx.mongodb.net
+  dbName: 'mybot',                // database name (automatically created by MongoDB)
+}));
+bot.variables({ money: 100 });
+bot.command({ name: 'work', code: '$incUserVar[money;25]Your money is now $getUserVar[money]' });
+bot.connect();
+```
+That's the only change required: all `$getUserVar`, `$setUserVar`, etc., will automatically use MongoDB. `bot.use(...)` must be called **before** `bot.connect()`.
+How to get free MongoDB: create a cluster on MongoDB Atlas (M0 tier), create a database user, whitelist your hosting IP in *Network Access*, and copy the *connection string*. Store it in the `MONGO_URI` environment variable, **do not write it in the code**.
+### Plugin Options
+| Option | Description |
+|---|---|
+| `uri` | MongoDB URI string (required). |
+| `dbName` | Database name. If empty, uses the database name from the URI, or `test`. |
+| `collection` | Collection name, defaults to `easydc`. Each variable = one document `{ _id, v, t }`. |
+| `cache` | Defaults to `true`: read data is cached in RAM for speed. **Change to `false` if multiple bot processes share the database**, otherwise data can become stale. |
+| `cacheLimit` | Maximum keys in cache (defaults to 10000). |
+| `client` | Custom `MongoClient` instance (will not be automatically closed by the bot). |
+| `clientOptions` | Additional options passed to `new MongoClient(uri, options)`. |
+If MongoDB cannot be reached, the bot **will not log in** and prints `Failed to connect to database: ...` (timeout is 10 seconds).
+### Migrating Old Data (JSON → MongoDB)
+A one-time script, run it in the bot's root folder before using the plugin:
+```js
+const { Database, copyDatabase } = require('easydc-js');
+const { MongoDatabase } = require('easydc-js/mongodb');
+(async () => {
+  const oldDb = new Database({ path: './easydc-data.json' });
+  const newDb = new MongoDatabase({ uri: process.env.MONGO_URI, dbName: 'mybot' });
+  await newDb.connect();
+  console.log(await copyDatabase(oldDb, newDb));     // { copied: 120, skipped: 0 }
+  await newDb.close();
+})();
+```
+Existing data in MongoDB will not be overwritten. Pass `{ overwrite: true }` as the third argument if you wish to overwrite it.
+### `$inc...Var`: Safely Incrementing Numbers
+The `$setUserVar[money;$math[$getUserVar[money]+10]]` pattern can **lose data** if two commands execute concurrently (both reading the old value). Instead, use:
+```
+$incUserVar[money;10]        $incUserVar[money;-5]       (decrease)
+$incServerVar  $incChannelVar  $incGlobalVar
+```
+`$incUserVar[name;amount;userID?]` executes sequentially per variable, ensuring they do not overwrite each other. This safety applies within a **single bot process**; if you run multiple bot instances on the same database, cross-process collisions can still occur.
+### Creating a Custom Plugin / Database Adapter
+A plugin is either a function or an object `{ name, install(bot, options) }`; `install` must be synchronous.
+```js
+bot.use({
+  name: 'hello',
+  install(bot) {
+    bot.addFunction({ name: '$hello', params: 0, run: () => 'Hello from plugin!' });
+  },
+});
+```
+A database adapter (for Redis, SQLite, etc.) just needs to be an object with the following methods; all of them can be `async`:
+| Method | Required | Description |
+|---|---|---|
+| `get(key)` | yes | Return the value (string) or `undefined` if missing. |
+| `set(key, value)` | yes | Store a string value. |
+| `delete(key)` | yes | Delete a key. |
+| `keys(prefix?)` | no | Needed for `copyDatabase`. |
+| `connect()` / `close()` | no | Called before logging into Discord / when the bot shuts down. |
+| `flush()` | no | Save pending data. |
+Install using `bot.setDatabase(adapter)` or `new Bot({ database: adapter })`.
+> **Changes from version 1.1:** `bot.getVar`, `bot.setVar`, `bot.resetVar` now return a **Promise** (use `await`). `$function` styled commands are unaffected.
+---
+## 13. Creating Custom Functions
 ```js
 bot.addFunction({
-  name: '$salam',
-  params: 1,                       // jumlah argumen tepat (atau pakai min/max)
-  description: 'Menyapa seseorang',
-  run: (ctx, [nama]) => `Selamat datang, ${nama}! (diminta oleh ${ctx.user.username})`,
+  name: '$greetUser',
+  params: 1,                       // exact number of arguments (or use min/max)
+  description: 'Greets someone',
+  run: (ctx, [name]) => `Welcome, ${name}! (requested by ${ctx.user.username})`,
 });
-bot.command({ name: 'tes', code: '$salam[Budi]' });
+bot.command({ name: 'test', code: '$greetUser[Budi]' });
 ```
-`run` boleh `async`. `ctx` berisi `bot`, `client`, `guild`, `channel`, `member`, `user`, `message`, `interaction`, `args`. Lempar `new Error('pesan')` bila gagal; pesan itu akan dicatat di log.
-Opsi `override: true` mengganti fungsi bawaan.
+`run` can be `async`. `ctx` contains `bot`, `client`, `guild`, `channel`, `member`, `user`, `message`, `interaction`, `args`. Throw `new Error('message')` on failure; the message will be printed to logs.
+The option `override: true` overwrites built-in functions.
-## 13. Memisah command ke banyak file
+## 14. Splitting Commands into Multiple Files
 ```
-proyek/
+project/
 ├── index.js
 └── commands/
-    ├── umum.js
-    └── moderasi.js
+    ├── general.js
+    └── moderation.js
 ```
 ```js
 bot.loadCommands('./commands');
 ```
-Setiap file mengekspor satu objek atau array. Tambahkan `type` untuk selain command biasa (`'slash'`, `'button'`, `'select'`, `'modal'`, `'autocomplete'`, `'contextMenu'`, atau nama event seperti `'memberJoin'`). Contoh lengkap: [`examples/advanced/lanjutan.js`](examples/advanced/lanjutan.js).
+Each file exports a single object or an array. Add a `type` for anything other than regular prefix commands (`'slash'`, `'button'`, `'select'`, `'modal'`, `'autocomplete'`, `'contextMenu'`, or an event name like `'memberJoin'`). Complete example: [`examples/advanced/lanjutan.js`](examples/advanced/lanjutan.js).
 ```js
 module.exports = [
-  { name: 'halo', code: 'Halo $username' },
-  { type: 'slash', name: 'ping', description: 'Cek ping', code: '$ping ms' },
-  { type: 'button', customId: 'ok_*', code: 'Oke!' },
-  { type: 'memberJoin', code: 'Selamat datang $mention' },
+  { name: 'hello', code: 'Hello $username' },
+  { type: 'slash', name: 'ping', description: 'Check ping', code: '$ping ms' },
+  { type: 'button', customId: 'ok_*', code: 'Ok!' },
+  { type: 'memberJoin', code: 'Welcome $mention' },
 ];
 ```
-## 14. Keamanan
+## 15. Security
-- **Jangan taruh token di kode** atau di GitHub. Pakai variabel lingkungan. Jika token bocor, segera *Reset Token* di Developer Portal.
-- Fungsi aksi dan manajemen (`$ban`, `$unban`, `$kick`, `$timeout`, `$addRole`, `$clear`, `$sendDM`, `$createChannel`, `$deleteChannel`, `$deleteRole`, `$lockChannel`, `$leaveServer`, ...) memakai **izin bot**, bukan izin pengirim. **Selalu** lindungi dengan `$onlyPerms[...]`, `$onlyAdmin`, atau `$onlyOwner` di baris pertama command.
-- Mention yang dikirim bot dibatasi ke user saja (`@everyone` dan role tidak akan menyebut siapa pun). Ubah lewat opsi `allowedMentions` bila perlu.
-- Kalkulator `$math` tidak memakai `eval`, jadi aman dari eksekusi kode.
-- Biarkan `debug: false` di produksi supaya detail error tidak tampil ke pengguna (tetap tercatat di konsol).
+- **Never put tokens in your code** or push them to GitHub. Use environment variables. If a token leaks, immediately *Reset Token* in the Developer Portal.
+- Action and management functions (`$ban`, `$unban`, `$kick`, `$timeout`, `$addRole`, `$clear`, `$sendDM`, `$createChannel`, `$deleteChannel`, `$deleteRole`, `$lockChannel`, `$leaveServer`, ...) run using **bot permissions**, not the sender's permissions. **Always** protect them with `$onlyPerms[...]`, `$onlyAdmin`, or `$onlyOwner` on the first line of the command.
+- Mentions sent by the bot are restricted to users only (`@everyone` and roles will not ping anyone). Modify this via the `allowedMentions` option if necessary.
+- The `$math` calculator does not use `eval`, making it safe from arbitrary code execution.
+- Leave `debug: false` in production so that detailed error messages are not revealed to users (they will still be logged to the console).
-## 15. Pemecahan masalah
+## 16. Troubleshooting
-| Masalah | Penyebab / solusi |
+| Issue | Cause / Solution |
 |---|---|
-| Bot online tapi tidak merespons `!ping` | Aktifkan **Message Content Intent** di Developer Portal. |
-| `Used disallowed intents` saat login | Aktifkan intent yang diminta di Developer Portal (Server Members / Message Content), atau kurangi `intents`. |
-| Event member masuk/keluar tidak jalan | Aktifkan **Server Members Intent**. |
-| Slash command tidak muncul | Undang bot dengan scope `applications.commands`. Pakai `slashGuild` agar langsung muncul; global bisa butuh waktu. |
-| `Fungsi $xxx tidak dikenal` | Salah ketik. Jika maksudnya teks biasa, tulis `\$xxx` (atau `$dollar`). |
-| `... membutuhkan N argumen` | Jumlah `;` tidak sesuai. Tulis `\;` bila `;` bagian dari teks. |
-| Variabel "belum dideklarasikan" | Tambahkan di `bot.variables({ ... })` sebelum `bot.connect()`. |
-| Tombol/select tidak merespons | Pastikan `customId` di tombol sama dengan di `bot.button({ customId })`. |
-| `Missing Permissions` di log | Bot kurang izin / posisi role bot di bawah role target. |
-| `Token belum diisi` | `process.env.TOKEN` kosong. Cek cara menjalankan di bagian 2. |
-| Interaksi gagal ("This interaction failed") | Proses > 3 detik. Taruh `$defer` di awal. |
-| Modal tidak muncul / "Modal harus jadi respons pertama" | Jangan pakai `$defer` atau kirim pesan sebelum `$addModal`. Modal hanya dari slash/tombol/select, bukan command prefix. |
-| Autocomplete kosong | Opsi harus dibuat dengan `autocomplete: true`, dan handler `bot.autocomplete({ command, option })` cocok. Proses harus selesai < 3 detik. |
-| `$eval ... dimatikan` | Tambahkan `eval: true` dan `owners: ['ID_KAMU']` pada `new Bot({...})`. |
-| Event ban / voice tidak jalan | Intent `GuildModeration` / `GuildVoiceStates` sudah aktif secara bawaan; jika kamu mengatur `intents` sendiri, tambahkan keduanya. |
+| Bot is online but does not respond to `!ping` | Enable **Message Content Intent** in the Developer Portal. |
+| `Used disallowed intents` when logging in | Enable requested intents in the Developer Portal (Server Members / Message Content), or reduce your `intents`. |
+| Member join/leave events are not working | Enable **Server Members Intent**. |
+| Slash commands do not appear | Invite the bot with the `applications.commands` scope. Use `slashGuild` for immediate updates; global commands can take time. |
+| `Unknown function $xxx` | Misspelling. If intended as plain text, write `\$xxx` (or `$dollar`). |
+| `... requires N arguments` | Semicolon `;` count mismatch. Write `\;` if the semicolon is part of the text. |
+| Variable "not declared" | Add it inside `bot.variables({ ... })` before calling `bot.connect()`. |
+| Buttons/select menus do not respond | Ensure the `customId` on the button matches the one in `bot.button({ customId })`. |
+| `Missing Permissions` in logs | The bot lacks permissions / the bot's highest role is below the target role. |
+| `Token not provided` | `process.env.TOKEN` is empty. Check how to run the bot in section 2. |
+| Interaction failed ("This interaction failed") | Process took > 3 seconds. Place `$defer` at the top of the command. |
+| Modal does not appear / "Modal must be the first response" | Do not use `$defer` or send messages before `$addModal`. Modals are only available from slash/button/select triggers, not prefix commands. |
+| Autocomplete list is empty | Options must be defined with `autocomplete: true`, and the `bot.autocomplete({ command, option })` handler must match. Process must finish in < 3 seconds. |
+| `Package "mongodb" not found` | Run `npm install mongodb` (on panel hosting: add `mongodb` to *Additional Node Packages*). |
+| `Failed to connect to database` | Check `MONGO_URI`, user & password, and whitelist your hosting IP in MongoDB Atlas (*Network Access*). Passwords with special characters (`@ : /`) must be URL-encoded. |
+| Data in MongoDB does not update / looks stale | There is more than one bot process running on the same database: set `cache: false`. |
+| `$eval ... is disabled` | Add `eval: true` and `owners: ['YOUR_ID']` inside `new Bot({...})`. |
+| Ban / voice events are not working | `GuildModeration` / `GuildVoiceStates` intents are enabled by default; if you set `intents` manually, add both. |
 ---
-## 16. Daftar semua fungsi
+## 17. List of All Functions
-Tanda `?` berarti argumen opsional. Daftar ini dibuat otomatis dari kode (`npm run docs`).
+The `?` symbol means the argument is optional. This list is automatically generated from the source code (`npm run docs`).
 <!-- FUNCTIONS:START -->
-### Info (user, server, bot, pesan, waktu)
+### Info (user, server, bot, message, time)
-| Fungsi | Keterangan |
+| Function | Description |
 |---|---|
-| `$username[userID?]` | Username (tanpa ID = pengirim) |
-| `$usertag[userID?]` | Tag user |
-| `$displayName[userID?]` | Nama tampilan (nickname server / nama global / username) |
-| `$nickname[userID?]` | Nickname di server (kosong -> username) |
-| `$authorID` | ID pengirim pesan / pengguna interaksi |
-| `$userAvatar[userID?;ukuran?]` | URL avatar (ukuran 16-4096) |
-| `$isBot[userID?]` | true/false: apakah user adalah bot |
-| `$userCreatedAt[userID?]` | Waktu akun dibuat (ms) |
-| `$mentioned[nomor;fallbackAuthor?]` | ID user yang di-mention ke-N (isi 2: yes = pakai pengirim bila tidak ada) |
-| `$mention[userID?]` | Mention user, contoh <@123> |
-| `$serverName` | Nama server |
-| `$serverID` | ID server |
-| `$serverIcon` | URL ikon server |
-| `$memberCount` | Jumlah member server |
-| `$ownerID` | ID pemilik server |
-| `$serverCreatedAt` | Waktu server dibuat (ms) |
-| `$roleCount` | Jumlah role |
-| `$channelCount` | Jumlah channel |
-| `$channelName[channelID?]` | Nama channel (tanpa ID = channel ini) |
-| `$channelID` | ID channel saat ini |
-| `$channelMention[channelID?]` | Mention channel, contoh <#123> |
-| `$roleName[roleID]` | Nama role |
-| `$roleMention[roleID]` | Mention role, contoh <@&123> |
-| `$botID` | ID bot |
-| `$botName` | Username bot |
-| `$ping` | Ping websocket (ms) |
-| `$uptime` | Lama bot menyala, contoh "1d 2h 3m 4s" |
-| `$serverCount` | Jumlah server tempat bot berada |
-| `$message[nomor?]` | Semua argumen setelah command, atau argumen ke-N |
-| `$argsCount` | Jumlah argumen |
-| `$messageID` | ID pesan / interaksi |
-| `$messageContent` | Isi lengkap pesan pemicu |
-| `$commandName` | Nama command yang berjalan |
-| `$option[nama]` | Nilai opsi slash command |
-| `$customID` | customId tombol/select yang ditekan |
-| `$interactionValues[nomor?]` | Nilai yang dipilih di select menu |
-| `$reactionEmoji` | Emoji pada event reaksi |
-| `$timestamp` | Waktu sekarang (ms) |
-| `$unix` | Waktu sekarang (detik) |
-| `$date[format?;ms?]` | Tanggal/jam. Token: YYYY MM DD HH mm ss. Zona waktu dari opsi timezone |
-| `$discordTime[ms?;gaya?]` | Format waktu Discord <t:..>. Gaya: t T d D f F R |
-### Teks, matematika & pengecekan
-| Fungsi | Keterangan |
+| `$username[userID?]` | Username (without ID = sender) |
+| `$usertag[userID?]` | User tag |
+| `$displayName[userID?]` | Display name (server nickname / global name / username) |
+| `$nickname[userID?]` | Nickname in the server (empty -> username) |
+| `$authorID` | ID of the message author / interaction user |
+| `$userAvatar[userID?;size?]` | Avatar URL (size 16-4096) |
+| `$isBot[userID?]` | true/false: whether the user is a bot |
+| `$userCreatedAt[userID?]` | Account creation timestamp (ms) |
+| `$mentioned[number;fallbackAuthor?]` | ID of the N-th mentioned user (if 2nd arg is yes = defaults to sender if absent) |
+| `$mention[userID?]` | Mention a user, e.g., <@123> |
+| `$serverName` | Server name |
+| `$serverID` | Server ID |
+| `$serverIcon` | Server icon URL |
+| `$memberCount` | Number of server members |
+| `$ownerID` | Server owner ID |
+| `$serverCreatedAt` | Server creation timestamp (ms) |
+| `$roleCount` | Number of roles |
+| `$channelCount` | Number of channels |
+| `$channelName[channelID?]` | Channel name (without ID = current channel) |
+| `$channelID` | Current channel ID |
+| `$channelMention[channelID?]` | Mention a channel, e.g., <#123> |
+| `$roleName[roleID]` | Role name |
+| `$roleMention[roleID]` | Mention a role, e.g., <@&123> |
+| `$botID` | Bot ID |
+| `$botName` | Bot username |
+| `$ping` | Websocket ping (ms) |
+| `$uptime` | Duration the bot has been online, e.g., "1d 2h 3m 4s" |
+| `$serverCount` | Number of servers the bot is in |
+| `$message[number?]` | All arguments after the command, or the N-th argument |
+| `$argsCount` | Argument count |
+| `$messageID` | Message / interaction ID |
+| `$messageContent` | Full text content of the triggering message |
+| `$commandName` | Name of the currently running command |
+| `$option[name]` | Value of a slash command option |
+| `$customID` | customId of the pressed button/select menu |
+| `$interactionValues[number?]` | Selected values in a select menu |
+| `$reactionEmoji` | Emoji from a reaction event |
+| `$timestamp` | Current timestamp (ms) |
+| `$unix` | Current timestamp (seconds) |
+| `$date[format?;ms?]` | Date/time string. Tokens: YYYY MM DD HH mm ss. Timezone comes from bot option |
+| `$discordTime[ms?;style?]` | Discord timestamp format <t:..>. Styles: t T d D f F R |
+### Text, Math & Validation
+| Function | Description |
 |---|---|
-| `$math[ekspresi]` | Hitung aman. Dukung + - * / % ^ ( ) sqrt abs round floor ceil min max pow pi e |
-| `$sum[a;b;...]` | Jumlah semua angka |
+| `$math[expression]` | Safe evaluation. Supports + - * / % ^ ( ) sqrt abs round floor ceil min max pow pi e |
+| `$sum[a;b;...]` | Sum of all numbers |
 | `$sub[a;b]` | a - b |
-| `$multiply[a;b;...]` | Kali semua angka |
+| `$multiply[a;b;...]` | Multiply all numbers |
 | `$divide[a;b]` | a / b |
-| `$modulo[a;b]` | Sisa bagi a % b |
-| `$round[angka;desimal?]` | Bulatkan angka |
-| `$max[a;b;...]` | Angka terbesar |
-| `$min[a;b;...]` | Angka terkecil |
-| `$random[min;max]` | Bilangan bulat acak (inklusif) |
-| `$randomText[a;b;...]` | Pilih salah satu teks secara acak |
-| `$numberSeparator[angka;pemisah?]` | 1234567 -> 1,234,567 |
-| `$toUpperCase[teks]` | HURUF BESAR |
-| `$toLowerCase[teks]` | huruf kecil |
-| `$capitalize[teks]` | Huruf pertama jadi besar |
-| `$titleCase[teks]` | Huruf Pertama Tiap Kata Besar |
-| `$trimSpace[teks]` | Hapus spasi di awal/akhir |
-| `$length[teks]` | Jumlah karakter |
-| `$reverse[teks]` | Balik urutan teks |
-| `$repeat[teks;jumlah]` | Ulang teks (maks 100x) |
-| `$substring[teks;awal;akhir?]` | Potong teks (indeks mulai 0) |
-| `$replaceText[teks;cari;ganti;batas?]` | Ganti teks (semua, atau N pertama) |
-| `$split[teks;pemisah;nomor]` | Ambil bagian ke-N setelah memecah teks |
-| `$urlEncode[teks]` | Encode untuk URL |
-| `$semicolon` | Karakter ; |
-| `$leftBracket` | Karakter [ |
-| `$rightBracket` | Karakter ] |
-| `$dollar` | Karakter $ |
-| `$isNumber[teks]` | true/false: apakah angka |
-| `$checkContains[teks;cari1;cari2;...]` | true bila teks memuat salah satu kata |
-| `$checkCondition[kondisi]` | true/false. Operator: == != > < >= <= && \|\| |
-| `$hasRole[roleID;userID?]` | true/false: member punya role |
-| `$hasPerms[izin1,izin2;userID?]` | true/false: member punya semua izin (nama izin discord.js) |
-| `$isAdmin[userID?]` | true/false: member administrator |
-| `$isOwner[userID?]` | true/false: user ada di daftar owners bot |
-| `$isTrue[teks]` | true bila teks bernilai true/yes/1/on |
-### Kontrol alur & batasan
-| Fungsi | Keterangan |
+| `$modulo[a;b]` | Remainder of division a % b |
+| `$round[number;decimals?]` | Round a number |
+| `$max[a;b;...]` | Largest number |
+| `$min[a;b;...]` | Smallest number |
+| `$random[min;max]` | Random integer (inclusive) |
+| `$randomText[a;b;...]` | Randomly select one text block |
+| `$numberSeparator[number;separator?]` | 1234567 -> 1,234,567 |
+| `$toUpperCase[text]` | UPPERCASE |
+| `$toLowerCase[text]` | lowercase |
+| `$capitalize[text]` | Capitalize the first letter |
+| `$titleCase[text]` | Capitalize The First Letter Of Each Word |
+| `$trimSpace[text]` | Trim leading/trailing spaces |
+| `$length[text]` | Character count |
+| `$reverse[text]` | Reverse string order |
+| `$repeat[text;count]` | Repeat text (max 100x) |
+| `$substring[text;start;end?]` | Extract substring (0-based index) |
+| `$replaceText[text;search;replace;limit?]` | Replace text (all, or first N occurrences) |
+| `$split[text;delimiter;number]` | Get the N-th element after splitting text |
+| `$urlEncode[text]` | URL encode a string |
+| `$semicolon` | Literal character ; |
+| `$leftBracket` | Literal character [ |
+| `$rightBracket` | Literal character ] |
+| `$dollar` | Literal character $ |
+| `$isNumber[text]` | true/false: whether it's a number |
+| `$checkContains[text;search1;search2;...]` | true if text contains any of the search words |
+| `$checkCondition[condition]` | true/false. Operators: == != > < >= <= && \|\| |
+| `$hasRole[roleID;userID?]` | true/false: member has role |
+| `$hasPerms[perms1,perms2;userID?]` | true/false: member has all permissions (discord.js permission names) |
+| `$isAdmin[userID?]` | true/false: member is an administrator |
+| `$isOwner[userID?]` | true/false: user is listed in the bot's owners |
+| `$isTrue[text]` | true if text evaluates to true/yes/1/on |
+### Flow Control & Constraints
+| Function | Description |
 |---|---|
-| `$if[kondisi]` | Mulai blok kondisi. Tutup dengan $endif |
-| `$elseif[kondisi]` | Kondisi alternatif |
-| `$else` | Jika semua kondisi sebelumnya salah |
-| `$endif` | Menutup blok $if |
-| `$stop[pesan?]` | Hentikan eksekusi (opsional kirim pesan) |
-| `$onlyIf[kondisi;pesan?]` | Lanjut hanya jika kondisi benar |
-| `$onlyPerms[Izin1,Izin2;pesan?]` | Lanjut hanya jika pengirim punya semua izin (mis. BanMembers) |
-| `$onlyBotPerms[Izin1,Izin2;pesan?]` | Lanjut hanya jika bot punya izin tersebut di server |
-| `$onlyAdmin[pesan?]` | Lanjut hanya jika pengirim administrator |
-| `$onlyOwner[pesan?]` | Lanjut hanya jika pengirim ada di opsi owners |
-| `$onlyForIDs[id1,id2;pesan?]` | Lanjut hanya untuk user dengan ID tertentu |
-| `$onlyInServer[pesan?]` | Lanjut hanya jika dipakai di server (bukan DM) |
-| `$argsCheck[syarat;pesan?]` | Cek jumlah argumen. "2" = minimal 2; juga >=1 <=3 >1 <3 =2 |
-| `$cooldown[waktu;pesan?]` | Cooldown per user per command. %time% di pesan = sisa waktu |
-| `$wait[waktu]` | Tunggu sebentar (maks 60 detik) |
-| `$deleteCommand` | Hapus pesan perintah milik pengirim setelah dijawab |
-| `$deleteIn[waktu]` | Hapus jawaban bot setelah waktu tertentu (maks 24 jam) |
-| `$ephemeral` | Slash/tombol: jawaban hanya terlihat oleh pengguna |
-| `$reply` | Jawab dengan fitur reply pada pesan perintah |
-| `$update` | Tombol/select: ubah pesan asal, bukan kirim pesan baru |
-| `$typing` | Tampilkan "sedang mengetik" |
-| `$defer` | Slash/tombol: tunda jawaban (untuk proses > 3 detik). Taruh $ephemeral sebelum ini bila perlu |
-| `$let[nama;nilai]` | Simpan variabel sementara (hanya selama command berjalan) |
-| `$get[nama]` | Ambil variabel sementara dari $let |
-### Variabel & database
-| Fungsi | Keterangan |
+| `$if[condition]` | Start conditional block. Close with $endif |
+| `$elseif[condition]` | Alternative condition |
+| `$else` | If all previous conditions are false |
+| `$endif` | Close $if block |
+| `$stop[message?]` | Halt execution (optionally send a message) |
+| `$onlyIf[condition;message?]` | Proceed only if the condition is true |
+| `$onlyPerms[Perms1,Perms2;message?]` | Proceed only if the sender has all permissions (e.g., BanMembers) |
+| `$onlyBotPerms[Perms1,Perms2;message?]` | Proceed only if the bot has those permissions in the server |
+| `$onlyAdmin[message?]` | Proceed only if the sender is an administrator |
+| `$onlyOwner[message?]` | Proceed only if the sender is in the owners option |
+| `$onlyForIDs[id1,id2;message?]` | Proceed only for specific user IDs |
+| `$onlyInServer[message?]` | Proceed only if used inside a server (not DMs) |
+| `$argsCheck[requirement;message?]` | Check argument count. "2" = at least 2; also supports >=1 <=3 >1 <3 =2 |
+| `$cooldown[time;message?]` | Cooldown per user per command. %time% in message = remaining time |
+| `$wait[time]` | Pause execution briefly (max 60 seconds) |
+| `$deleteCommand` | Delete the command message sent by the user after replying |
+| `$deleteIn[time]` | Delete the bot's reply after a certain time (max 24 hours) |
+| `$ephemeral` | Slash/button: make reply visible only to the user |
+| `$reply` | Reply to the triggering command message directly using inline replies |
+| `$update` | Button/select: edit original message instead of sending a new one |
+| `$typing` | Display "is typing" status |
+| `$defer` | Slash/button: defer reply (for processes > 3s). Put $ephemeral before this if needed |
+| `$let[name;value]` | Save a temporary variable (lasts only during command execution) |
+| `$get[name]` | Retrieve a temporary variable from $let |
+### Variables & Database
+| Function | Description |
 |---|---|
-| `$setUserVar[nama;nilai;userID?]` | Simpan variabel user (harus dideklarasikan dengan bot.variables) |
-| `$getUserVar[nama;userID?]` | Baca variabel user |
-| `$resetUserVar[nama;userID?]` | Kembalikan variabel user ke nilai awal |
-| `$setServerVar[nama;nilai;serverID?]` | Simpan variabel server (harus dideklarasikan dengan bot.variables) |
-| `$getServerVar[nama;serverID?]` | Baca variabel server |
-| `$resetServerVar[nama;serverID?]` | Kembalikan variabel server ke nilai awal |
-| `$setChannelVar[nama;nilai;channelID?]` | Simpan variabel channel (harus dideklarasikan dengan bot.variables) |
-| `$getChannelVar[nama;channelID?]` | Baca variabel channel |
-| `$resetChannelVar[nama;channelID?]` | Kembalikan variabel channel ke nilai awal |
-| `$setGlobalVar[nama;nilai]` | Simpan variabel global |
-| `$getGlobalVar[nama]` | Baca variabel global |
-| `$resetGlobalVar[nama]` | Kembalikan variabel global ke nilai awal |
-### Embed
-| Fungsi | Keterangan |
+| `$setUserVar[name;value;userID?]` | Save a user variable (must be declared via bot.variables) |
+| `$getUserVar[name;userID?]` | Read a user variable |
+| `$resetUserVar[name;userID?]` | Reset a user variable to its initial value |
+| `$incUserVar[name;amount;userID?]` | Increment a numeric user var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setServerVar[name;value;serverID?]` | Save a server variable (must be declared via bot.variables) |
+| `$getServerVar[name;serverID?]` | Read a server variable |
+| `$resetServerVar[name;serverID?]` | Reset a server variable to its initial value |
+| `$incServerVar[name;amount;serverID?]` | Increment a numeric server var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setChannelVar[name;value;channelID?]` | Save a channel variable (must be declared via bot.variables) |
+| `$getChannelVar[name;channelID?]` | Read a channel variable |
+| `$resetChannelVar[name;channelID?]` | Reset a channel variable to its initial value |
+| `$incChannelVar[name;amount;channelID?]` | Increment a numeric channel var (negative = decrease). Safe from race conditions. Prints nothing |
+| `$setGlobalVar[name;value]` | Save a global variable |
+| `$getGlobalVar[name]` | Read a global variable |
+| `$resetGlobalVar[name]` | Reset a global variable to its initial value |
+| `$incGlobalVar[name;amount]` | Increment a numeric global var (negative = decrease) |
+### Embeds
+| Function | Description |
 |---|---|
-| `$newEmbed` | Mulai embed baru (embed pertama dibuat otomatis). Maks 10 |
-| `$title[teks]` | Judul embed (maks 256) |
-| `$embedURL[url]` | Tautan pada judul embed |
-| `$description[teks]` | Isi embed (maks 4096) |
-| `$color[#hex|nama|random]` | Warna embed |
-| `$footer[teks;ikonURL?]` | Footer embed (maks 2048) |
-| `$author[nama;ikonURL?;url?]` | Penulis embed (maks 256) |
-| `$thumbnail[url]` | Gambar kecil embed |
-| `$image[url]` | Gambar besar embed |
-| `$addField[nama;isi;inline?]` | Tambah field (maks 25; inline = true/false) |
-| `$addTimestamp[ms?]` | Tambah cap waktu di embed (default: sekarang) |
-### Tombol & select menu
-| Fungsi | Keterangan |
+| `$newEmbed` | Start a new embed block (the first one is created automatically). Max 10 |
+| `$title[text]` | Embed title (max 256) |
+| `$embedURL[url]` | URL link on the embed title |
+| `$description[text]` | Embed description body (max 4096) |
+| `$color[#hex|name|random]` | Embed color |
+| `$footer[text;iconURL?]` | Embed footer text (max 2048) |
+| `$author[name;iconURL?;url?]` | Embed author name (max 256) |
+| `$thumbnail[url]` | Embed small thumbnail image URL |
+| `$image[url]` | Embed large main image URL |
+| `$addField[name;value;inline?]` | Add a field (max 25; inline = true/false) |
+| `$addTimestamp[ms?]` | Add a timestamp to the embed (default: current time) |
+### Buttons & Select Menus
+| Function | Description |
 |---|---|
-| `$addUserSelect[customID;placeholder?;min?;max?]` | Select menu pilih user (nilai terpilih lewat $interactionValues) |
-| `$addRoleSelect[customID;placeholder?;min?;max?]` | Select menu pilih role (nilai terpilih lewat $interactionValues) |
-| `$addMentionableSelect[customID;placeholder?;min?;max?]` | Select menu pilih user atau role (nilai terpilih lewat $interactionValues) |
-| `$addChannelSelect[customID;placeholder?;min?;max?;tipe?]` | Select menu pilih channel (nilai terpilih lewat $interactionValues). Tipe: text voice category announcement stage forum, pisah koma |
-| `$newRow` | Mulai baris tombol baru (otomatis tiap 5 tombol) |
-| `$addButton[label;gaya;customID/URL;nonaktif?;emoji?]` | Tambah tombol. Gaya: primary secondary success danger link |
-| `$addSelectMenu[customID;placeholder?;min?;max?]` | Buat select menu (lanjutkan dengan $addSelectOption) |
-| `$addSelectOption[label;nilai;deskripsi?;emoji?;default?]` | Tambah opsi ke select menu terakhir (maks 25) |
-### Aksi & moderasi
-| Fungsi | Keterangan |
+| `$addUserSelect[customID;placeholder?;min?;max?]` | User select menu (retrieve selected items via $interactionValues) |
+| `$addRoleSelect[customID;placeholder?;min?;max?]` | Role select menu (retrieve selected items via $interactionValues) |
+| `$addMentionableSelect[customID;placeholder?;min?;max?]` | Mentionable select menu (retrieve selected items via $interactionValues) |
+| `$addChannelSelect[customID;placeholder?;min?;max?;types?]` | Channel select menu (retrieve via $interactionValues). Types: text voice category announcement stage forum, comma-separated |
+| `$newRow` | Start a new action row for buttons (automatic every 5 buttons) |
+| `$addButton[label;style;customID/URL;disabled?;emoji?]` | Add a button. Styles: primary secondary success danger link |
+| `$addSelectMenu[customID;placeholder?;min?;max?]` | Create a base string select menu (follow up with $addSelectOption) |
+| `$addSelectOption[label;value;description?;emoji?;default?]` | Add a choice to the last select menu (max 25) |
+### Actions & Moderation
+| Function | Description |
 |---|---|
-| `$sendMessage[channelID;teks]` | Kirim pesan ke channel lain |
-| `$sendDM[userID;teks]` | Kirim DM ke user |
-| `$react[emoji1;emoji2;...]` | Beri reaksi pada pesan perintah |
-| `$ban[userID;alasan?;hariHapusPesan?]` | Ban user (hapus pesan 0-7 hari) |
-| `$kick[userID;alasan?]` | Kick member |
-| `$timeout[userID;waktu;alasan?]` | Timeout member (maks 28 hari) |
-| `$untimeout[userID;alasan?]` | Cabut timeout member |
-| `$addRole[userID;roleID;alasan?]` | Beri role |
-| `$removeRole[userID;roleID;alasan?]` | Cabut role |
-| `$setNickname[userID;nickname]` | Ubah nickname (kosongkan untuk reset) |
-| `$clear[jumlah]` | Hapus 1-100 pesan terakhir (maks umur 14 hari). Mengembalikan jumlah terhapus |
-| `$slowmode[detik]` | Atur slowmode channel (0 = mati, maks 21600) |
-### Pesan, lampiran, polling, thread & webhook
-| Fungsi | Keterangan |
+| `$sendMessage[channelID;text]` | Send a message to another channel |
+| `$sendDM[userID;text]` | Send a DM to a user |
+| `$react[emoji1;emoji2;...]` | Add reactions to the command message |
+| `$ban[userID;reason?;deleteMessageDays?]` | Ban a user (delete messages 0-7 days) |
+| `$kick[userID;reason?]` | Kick a member |
+| `$timeout[userID;duration;reason?]` | Timeout a member (max 28 days) |
+| `$untimeout[userID;reason?]` | Remove timeout from a member |
+| `$addRole[userID;roleID;reason?]` | Give a role to a member |
+| `$removeRole[userID;roleID;reason?]` | Remove a role from a member |
+| `$setNickname[userID;nickname]` | Change nickname (leave empty to reset) |
+| `$clear[amount]` | Purge last 1-100 messages (max 14 days old). Returns count of deleted messages |
+| `$slowmode[seconds]` | Set channel slowmode rate (0 = disabled, max 21600) |
+### Messages, Attachments, Polls, Threads & Webhooks
+| Function | Description |
 |---|---|
-| `$editMessage[messageID;teks;channelID?]` | Edit pesan milik bot sendiri |
-| `$deleteMessage[messageID;channelID?]` | Hapus satu pesan |
-| `$pinMessage[messageID;channelID?]` | Sematkan (pin) pesan |
-| `$unpinMessage[messageID;channelID?]` | Lepas pin pesan |
-| `$addReaction[messageID;emoji;channelID?]` | Beri reaksi pada pesan tertentu |
-| `$messageContentOf[messageID;channelID?]` | Isi teks pesan tertentu |
-| `$messageAuthorOf[messageID;channelID?]` | ID pengirim pesan tertentu |
-| `$addAttachment[url;nama?]` | Lampirkan file dari URL http(s) ke jawaban (maks 10) |
-| `$addTextFile[namaFile;isi]` | Lampirkan file teks buatan sendiri (maks 1 MB) |
-| `$poll[pertanyaan;jam;multi;opsi1;opsi2;...]` | Buat polling (jam 1-768, multi = true/false, 2-10 opsi) |
-| `$sendWebhook[webhookURL;teks;username?;avatarURL?]` | Kirim pesan lewat URL webhook Discord |
-| `$createThread[nama;messageID?;arsipOtomatisMenit?]` | Buat thread (dari pesan bila messageID diisi). Arsip: 60/1440/4320/10080. Mengembalikan ID thread |
-| `$archiveThread[threadID?;kunci?]` | Arsipkan thread (kunci = true untuk sekalian dikunci) |
-| `$addThreadMember[userID;threadID?]` | Tambahkan user ke thread |
-| `$removeThreadMember[userID;threadID?]` | Keluarkan user dari thread |
-| `$createForumPost[forumID;judul;isi]` | Buat postingan di channel forum. Mengembalikan ID thread |
-### Manajemen server (ban, channel, role, undangan, emoji, event, voice)
-| Fungsi | Keterangan |
+| `$editMessage[messageID;text;channelID?]` | Edit a message belonging to the bot itself |
+| `$deleteMessage[messageID;channelID?]` | Delete a single message |
+| `$pinMessage[messageID;channelID?]` | Pin a message |
+| `$unpinMessage[messageID;channelID?]` | Unpin a message |
+| `$addReaction[messageID;emoji;channelID?]` | Add reaction to a specific message |
+| `$messageContentOf[messageID;channelID?]` | Fetch text content of a specific message |
+| `$messageAuthorOf[messageID;channelID?]` | Fetch author ID of a specific message |
+| `$addAttachment[url;name?]` | Attach a file from a http(s) URL to the response (max 10) |
+| `$addTextFile[fileName;content]` | Attach a custom text file generated on the fly (max 1 MB) |
+| `$poll[question;hours;multi;option1;option2;...]` | Create a poll (hours 1-768, multi = true/false, 2-10 options) |
+| `$sendWebhook[webhookURL;text;username?;avatarURL?]` | Send a message via a Discord Webhook URL |
+| `$createThread[name;messageID?;autoArchiveMinutes?]` | Create a thread (from a message if messageID is provided). Archive: 60/1440/4320/10080. Returns thread ID |
+| `$archiveThread[threadID?;lock?]` | Archive a thread (lock = true to also lock it) |
+| `$addThreadMember[userID;threadID?]` | Add a user to a thread |
+| `$removeThreadMember[userID;threadID?]` | Remove a user from a thread |
+| `$createForumPost[forumID;title;content]` | Create a post inside a forum channel. Returns thread ID |
+### Server Management (Bans, Channels, Roles, Invites, Emojis, Events, Voice)
+| Function | Description |
 |---|---|
-| `$unban[userID;alasan?]` | Cabut ban user |
-| `$isBanned[userID]` | true/false: user sedang di-ban di server ini |
-| `$banCount` | Jumlah user ter-ban (dibaca maks 1000 teratas) |
-| `$createChannel[nama;tipe?;parentID?;topik?]` | Buat channel. Tipe: text voice category announcement stage forum. Mengembalikan ID |
-| `$deleteChannel[channelID;alasan?]` | Hapus channel/thread (menghapus channel saat ini membuat jawaban gagal terkirim) |
-| `$setChannelName[channelID;nama;alasan?]` | Ubah nama channel |
-| `$setChannelTopic[channelID;topik;alasan?]` | Ubah topik channel |
-| `$lockChannel[channelID?;alasan?]` | Kunci channel: @everyone tidak bisa mengirim pesan |
-| `$unlockChannel[channelID?;alasan?]` | Buka kunci channel (kembali ke pengaturan semula) |
-| `$createInvite[channelID?;umurDetik?;maxPakai?]` | Buat link undangan. Umur 0-604800 (0 = selamanya), maxPakai 0-100. Mengembalikan URL |
-| `$channelType[channelID?]` | Tipe channel: text voice category announcement stage forum dst. |
-| `$createRole[nama;warna?;hoist?;mentionable?;alasan?]` | Buat role. Mengembalikan ID |
-| `$deleteRole[roleID;alasan?]` | Hapus role |
-| `$setRoleName[roleID;nama;alasan?]` | Ubah nama role |
-| `$setRoleColor[roleID;warna;alasan?]` | Ubah warna role (#hex / nama / random) |
-| `$memberRoles[userID?]` | Daftar ID role member, dipisah koma |
-| `$createEmoji[nama;url]` | Tambah emoji dari URL gambar. Mengembalikan emoji siap pakai |
-| `$deleteEmoji[emojiID]` | Hapus emoji server |
-| `$createEvent[nama;mulaiMs;selesaiMs;lokasi;deskripsi?]` | Buat scheduled event (di luar Discord). Waktu dalam ms (lihat $timestamp). Mengembalikan ID |
-| `$moveMember[userID;voiceChannelID]` | Pindahkan member ke voice channel lain |
-| `$disconnectMember[userID]` | Keluarkan member dari voice channel |
-| `$leaveServer[serverID?]` | Bot keluar dari server. Hanya untuk owner bot |
-### Modal, autocomplete & sasaran
-| Fungsi | Keterangan |
+| `$unban[userID;reason?]` | Revoke a user's ban |
+| `$isBanned[userID]` | true/false: whether the user is currently banned in this server |
+| `$banCount` | Number of banned users (reads max top 1000) |
+| `$createChannel[name;type?;parentID?;topic?]` | Create a channel. Types: text voice category announcement stage forum. Returns ID |
+| `$deleteChannel[channelID;reason?]` | Delete a channel/thread (deleting the active channel makes sending the reply fail) |
+| `$setChannelName[channelID;name;reason?]` | Change channel name |
+| `$setChannelTopic[channelID;topic;reason?]` | Change channel topic |
+| `$lockChannel[channelID?;reason?]` | Lock a channel: @everyone will be unable to send messages |
+| `$unlockChannel[channelID?;reason?]` | Unlock a channel (reverts to default configurations) |
+| `$createInvite[channelID?;maxAgeSeconds?;maxUses?]` | Create an invite link. Age 0-604800 (0 = infinite), maxUses 0-100. Returns URL |
+| `$channelType[channelID?]` | Channel type string: text voice category announcement stage forum etc. |
+| `$createRole[name;color?;hoist?;mentionable?;reason?]` | Create a role. Returns ID |
+| `$deleteRole[roleID;reason?]` | Delete a role |
+| `$setRoleName[roleID;name;reason?]` | Change role name |
+| `$setRoleColor[roleID;color;reason?]` | Change role color (#hex / name / random) |
+| `$memberRoles[userID?]` | Comma-separated list of member role IDs |
+| `$createEmoji[name;url]` | Create a guild emoji from an image URL. Returns the ready-to-use emoji string |
+| `$deleteEmoji[emojiID]` | Delete a server emoji |
+| `$createEvent[name;startMs;endMs;location;description?]` | Create a scheduled guild event (external location type). Time in ms. Returns ID |
+| `$moveMember[userID;voiceChannelID]` | Move a member to another voice channel |
+| `$disconnectMember[userID]` | Disconnect a member from a voice channel |
+| `$leaveServer[serverID?]` | Force the bot to leave a server. Bot owners only |
+### Modals, Autocomplete & Target Scope
+| Function | Description |
 |---|---|
-| `$addModal[customID;judul]` | Tampilkan form pop-up (modal). Jadi respons pertama; teks lain diabaikan. Isi dengan $addTextInput |
-| `$addTextInput[customID;label;gaya?;placeholder?;wajib?;min?;max?;nilaiAwal?]` | Tambah kolom isian ke modal (maks 5). Gaya: short / paragraph |
-| `$modalValue[customIDKolom]` | Isi kolom modal yang dikirim pengguna (dipakai di handler bot.modal) |
-| `$focusedValue` | Autocomplete: teks yang sedang diketik pengguna |
-| `$focusedOption` | Autocomplete: nama opsi yang sedang diisi |
-| `$addChoice[nama;nilai?]` | Autocomplete: tambah satu pilihan (maks 25). Nilai bawaan = nama |
-| `$targetID` | ID sasaran: user/pesan yang diklik kanan, atau objek event (channel/role/thread/voice/ban) |
-| `$targetName` | Nama sasaran (username / nama channel / nama role) |
-| `$targetContent` | Isi pesan yang diklik kanan (context menu pesan) |
-| `$messageFrom[nomor]` | Seluruh teks argumen mulai dari kata ke-N (spasi dan baris baru dipertahankan) |
-### Eval (khusus owner)
-| Fungsi | Keterangan |
+| `$addModal[customID;title]` | Show a pop-up form (modal). Must be the first response; other texts are ignored. Build inputs using $addTextInput |
+| `$addTextInput[customID;label;style?;placeholder?;required?;min?;max?;initialValue?]` | Add an input field to a modal (max 5). Styles: short / paragraph |
+| `$modalValue[columnCustomID]` | Retrieve submitted modal input text values (used inside bot.modal handlers) |
+| `$focusedValue` | Autocomplete: text currently typed by the user |
+| `$focusedOption` | Autocomplete: name of the option currently being focused |
+| `$addChoice[name;value?]` | Autocomplete: add a dynamic choice (max 25). Default value = name |
+| `$targetID` | Target ID: right-clicked user/message, or the target entity of an event (channel/role/thread/voice/ban) |
+| `$targetName` | Target name (username / channel name / role name) |
+| `$targetContent` | Target message content (right-click message context menu) |
+| `$messageFrom[number]` | The entire message string starting from the N-th word (spaces and newlines are preserved) |
+### Eval (Owner Only)
+| Function | Description |
 |---|---|
-| `$eval[kode]` | Jalankan kode versi port ($fungsi) dari teks saat berjalan. Khusus owner, butuh opsi eval: true |
-| `$jsEval[kodeJavaScript]` | Jalankan kode discord.js/JavaScript asli. Variabel: ctx client bot guild channel message user member interaction discord db require. Khusus owner, butuh opsi eval: true |
+| `$eval[code]` | Dynamically execute wrapper-version ($function) syntax string during runtime. Requires eval: true and owner status |
+| `$jsEval[javascriptCode]` | Dynamically execute native discord.js/JavaScript code. Variables: ctx client bot guild channel message user member interaction discord db require. Requires eval: true and owner status |
-<!-- FUNCTIONS:END -->
+<!-- FUNCTIONS:START -->
 ---
-## Yang belum didukung
+## What is Not Supported Yet
-Package ini belum mencakup seluruh discord.js. Belum ada: **voice/musik** (memutar audio), **sharding**, **AutoMod rules**, **stiker**, pengaturan permission per-channel yang rinci, dan Components V2. Untuk itu pakai `bot.client` (client discord.js asli) atau tambahkan fungsi lewat `bot.addFunction`.
+This package does not cover 100% of discord.js capabilities. The following features are currently missing: database adapters other than JSON and MongoDB (SQLite, Redis, etc., though you can build your own adapter, see section 12), **voice/music support** (audio streaming), **sharding**, **AutoMod rules**, **stickers**, granular channel permission overrides, and Components V2. For these features, use `bot.client` (native discord.js client) or inject custom functionalities via `bot.addFunction`.
-## Riwayat versi
+## Version History
-- **1.1.0**: `$unban` dan manajemen server (channel, role, undangan, emoji, event, voice), edit/hapus/pin pesan, lampiran, poll, webhook, thread & forum, modal, autocomplete, context menu, select user/role/channel, 9 event baru, `$eval` / `$jsEval` / `bot.evalCommand`. Intent bawaan bertambah `GuildModeration` dan `GuildVoiceStates`.
-- **1.0.0**: rilis pertama.
+- **1.2.0**: Plugin system architecture (`bot.use`, `bot.setDatabase`), official **MongoDB** plugin support (`easydc-js/mongodb`), `copyDatabase` migration toolkit for JSON files, `$incUserVar` and relative wrapper extensions (atomic number adjustment). `bot.getVar/setVar/resetVar` are now asynchronous.
+- **1.1.0**: Added `$unban` and full guild management suites (channels, roles, invites, emojis, events, voice actions), edit/delete/pin message commands, file attachment mechanisms, poll generation, webhook triggers, threads & forums integration, modal setups, autocomplete parameters, context menus, user/role/channel dedicated selector components, 9 brand new lifecycle events, and `$eval` / `$jsEval` / `bot.evalCommand`. Default intents expanded to include `GuildModeration` and `GuildVoiceStates`.
+- **1.0.0**: Initial release.
-## Lisensi
+## License
 MIT