diff --git a/kite-docs/docs/examples/_category_.json b/kite-docs/docs/examples/_category_.json new file mode 100644 index 00000000..c971a2a4 --- /dev/null +++ b/kite-docs/docs/examples/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Examples", + "position": 3, + "collapsed": false, + "link": { + "type": "generated-index", + "description": "Some examples for building your own commands and event listeners with Kite." + } +} diff --git a/kite-docs/docs/examples/cooldowns.md b/kite-docs/docs/examples/cooldowns.md new file mode 100644 index 00000000..f48966f4 --- /dev/null +++ b/kite-docs/docs/examples/cooldowns.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 2 +--- + +# Command Cooldowns + +Add cooldowns to your commands or event listeners to prevent spam and have more control over your commands. + +![Cooldown Result](./img/cooldown-result.png) + +## Step 1 - Creating a variable + +- Create a variable named \"cooldown\" from your [Kite](https://kite.onl/) dashboard - **Stored Variables** tab. +- Set the variable as scoped. + +:::info +### Usage of scopes ⚙️ + +- **`user.id` - for user-specific cooldowns** + - _if `x` user invokes the command, it won't affect `y` user._ +- **`guild.id` - for server-wide cooldowns** + - _if `x` user invokes the command, **all the users** in the server will be on cooldown for using the command._ +- **`0` - for global cooldown** + - _if `x` user invokes the command in any server, all the users across all the server the bot is present in would be on cooldown for using the command._ + +::: + +## Step 2 - Comparing values + +- Add these blocks before your actual command flow/actions : + - **Get Stored Variable** + - **Comparison Condition** + +**Get Stored Variable** +- **Variable** : `cooldown` +- **Scope** : `{{user.id}}` / `{{guild.id}}` / `0` [ see above for correct usage ] + +**Comparison Condition** +- **Base Value :** +```go +{{now().Unix() - (result('GET_VARIABLE') ?? 0)}} +``` +:::note +Replace 'GET_VARIABLE' with your actual block's name. +::: + +- **Match Condition** + - **Comparison Mode** - `LESS THAN` + - **Comparison Value :** +```go +{{duration("2m").Seconds()}} +``` +:::note +Replace "2m" with your desired duration. (see below) +::: + +::::info +### 📌 Correct Usage for `duration` + +- Valid time units are \"s\", \"m\", \"h\". +_for eg._ + - if you want 2 hour cooldown - `{{duration("2h").Seconds()}}` + - 2 hour 30 mins - `{{duration("2h30m").Seconds()}}` + - 2 hour 30 mins 5 seconds - `{{duration("2h30m5s").Seconds()}}` + - 20 m 10 s - `{{duration("20m10s").Seconds()}}` + +:::warning +Days tag - **\"d\" is not accepted** +- If you want `x days` cooldown, you'll have to convert it to hours. + - _for eg._ : 4 days = **96h** , 2d 3h = **51h** , etc. + +::: +:::: + +## Step 3 - Response + +- **_if the condition is true_** : + - _You're on cooldown. You can run the command again - ``_ +- **else** : + - _connect your original command flow_ + +## Step 4 - Setting variable value +At the end of your actual command flow, add the **Set Stored Variable** block +- **Variable** : `cooldown` +- **Scope** : `{{user.id}}` / `{{guild.id}}` / `0` [ see above for correct usage ] +- **Operation** - `overwrite` +- **Value** - `{{now().Unix()}}` + +![Cooldown Flow](./img/cooldowns-flow.png) + +:::tip +*If you have multiple commands where you want to have a separate cooldown for each command, you can create command-wise scopes.* + +Just add your command name before the actual scope. *for eg.,* +I've 2 commands `/echo` & `/ping` and I want to add user cooldown to both. In this case I'll use the following scopes: + - `echo-{{user.id}}` + - `ping-{{user.id}}` + +::: diff --git a/kite-docs/docs/examples/echo.md b/kite-docs/docs/examples/echo.md new file mode 100644 index 00000000..45c8dd58 --- /dev/null +++ b/kite-docs/docs/examples/echo.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 1 +--- + +import EmbedFlowNode from "../../src/components/EmbedFlowNode"; + +# Beginner - Echo Command + +A simple echo command that repeats your texts to get new users started with the basic structure and feature of the command builder. + +![Echo Demo](./img/echo-demo.gif) + +## 🌟 Creating your command +- Go to commands section of your Kite dashboard and make a command with the name echo. + +## 📝 Adding arguments +- Now that you've created your command, go to `Options` section of your command builder and select the **Command Arguments** block. + +- Connect this block to the little purple dot of your command name. +- Inside the **Command Arguments** block settings, add these : + - **Name** - `text` + - **Description** - `text to echo` + - **Argument Type** - Text + - **Argument Required** - True + +:::note +Arguments name can only be in small letters and can't contain any special characters except for an underscore ( \_ ). +If you want to add a space in argument's name use the underscore ( \_ ). +::: + +## 💬 Sending message +- From the actions menu, select the **Create Channel Message** block. + +- Set the target channel as `{{channel.id}}` +- Click **Edit Message** and then **Add embed** + - In the description box, put `{{arg('text')}}` + - For the Author section, put `{{user.username}}` in the name field and `{{user.avatar_url}}` in the Icon URL field. +- Exit the message editor. + +![Echo Embed Example](./img/echo-embed.png) + +## ✏️ Acknowledging your command +:::info +Discord requires interactions (slash commands, modals & buttons) to compulsorily have a "response" otherwise it shows a red alert on your screend saying "This interaction failed." even if your command works as expected. To prevent this, we use the **Create Response** block. +::: + +- Add the **Create Response Message** block after the previous block. + +- In the response field type anything acknowledging that user's command is successful. (for eg. "doneso") +- Scroll down on the block settings, and turn off the "Public Response" to make it visible only to the user who ran the command. + +![Echo Command Flow](./img/echo-flow.png) + +## 💌 Save your command +- Click **Save Changes** at the top of your page. +- Voilà! You've created your first command. +> It can take up to a minute for the changes to be deployed. This is indicated by the orange circle in the command list. It's advisable to wait until the orange circle changes to a green checkmark. +- Refresh your Discord client and run the command in your server. + +:::tip +You can add the **Command Permissions** block along-side your arguments block to restrict the usage of command to users with certain permissions. +::: diff --git a/kite-docs/docs/examples/img/cooldown-result.png b/kite-docs/docs/examples/img/cooldown-result.png new file mode 100644 index 00000000..a0853443 Binary files /dev/null and b/kite-docs/docs/examples/img/cooldown-result.png differ diff --git a/kite-docs/docs/examples/img/cooldowns-flow.png b/kite-docs/docs/examples/img/cooldowns-flow.png new file mode 100644 index 00000000..a4133b1a Binary files /dev/null and b/kite-docs/docs/examples/img/cooldowns-flow.png differ diff --git a/kite-docs/docs/examples/img/echo-demo.gif b/kite-docs/docs/examples/img/echo-demo.gif new file mode 100644 index 00000000..c1928035 Binary files /dev/null and b/kite-docs/docs/examples/img/echo-demo.gif differ diff --git a/kite-docs/docs/examples/img/echo-embed.png b/kite-docs/docs/examples/img/echo-embed.png new file mode 100644 index 00000000..e3c2f0a6 Binary files /dev/null and b/kite-docs/docs/examples/img/echo-embed.png differ diff --git a/kite-docs/docs/examples/img/echo-flow.png b/kite-docs/docs/examples/img/echo-flow.png new file mode 100644 index 00000000..9a466c38 Binary files /dev/null and b/kite-docs/docs/examples/img/echo-flow.png differ