> ## Documentation Index
> Fetch the complete documentation index at: https://kaoribot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TagScript Reference

> Complete guide to TagScript syntax for advanced custom commands.

Kaori uses the powerful [TagScript](https://tagscript.js.org/) engine to allow for advanced logic in custom commands.

## Variables

### User Variables

| Variable         | Description                       |
| :--------------- | :-------------------------------- |
| `{user}`         | Mentions the user.                |
| `{user.id}`      | User's ID.                        |
| `{user.tag}`     | User's handle (e.g. `User#1234`). |
| `{user.name}`    | User's username.                  |
| `{user.mention}` | Same as `{user}`.                 |

### Server & Channel

| Variable              | Description         |
| :-------------------- | :------------------ |
| `{guild}`             | Server Name.        |
| `{guild.id}`          | Server ID.          |
| `{guild.memberCount}` | Total member count. |
| `{channel}`           | Channel Mention.    |
| `{channel.id}`        | Channel ID.         |
| `{channel.name}`      | Channel Name.       |

### Arguments

| Variable            | Description                                          |
| :------------------ | :--------------------------------------------------- |
| `{args}`            | All arguments provided by the user, joined by space. |
| `{target}`          | Value of option named "target".                      |
| `{reason}`          | Value of option named "reason".                      |
| `{any_option_name}` | Value of any defined option.                         |

## Logic & Control Flow

### If Statements

Check conditions and run different code.

```ts-tags theme={null}
{if(condition):part true|part false}
```

**Operators**: `==`, `!=`, `>`, `<`, `>=`, `<=`, `~` (contains).

**Examples**:

```ts-tags theme={null}
{if({args}==):You provided no args!|Args: {args}}
{if({user.id}==123456789):Welcome Admin!|Welcome User!}
```

### Randomness

Generate random content.

* **Random Number**: `{random:min,max}`

  ```ts-tags theme={null}
  Rolled: {random:1,6}
  ```
* **Fifty-Fifty**: `{5050:Head|Tails}`

  ```ts-tags theme={null}
  Coin flip: {5050:Heads|Tails}
  ```
* **Random Choice** (from list): *To implement lists, uses advanced string splitting or helper tags - specific list tags coming soon.*

## Math

Perform calculations using `{math:expression}`. Supported operators: `+`, `-`, `*`, `/`, `%` (modulo), `^` (power).

```ts-tags theme={null}
{math:10 + 5} -> 15
{math:{args} * 2} -> (Multiplies user input by 2)
```

## Embed Builder

Create rich embeds directly in the response.

| Tag                           | Description                                                                                      |
| :---------------------------- | :----------------------------------------------------------------------------------------------- |
| `{embed(title):Text}`         | Set Title.                                                                                       |
| `{embed(desc):Text}`          | Set Description.                                                                                 |
| `{embed(color):#Hex}`         | Set Color.                                                                                       |
| `{embed(footer):Text}`        | Set Footer text.                                                                                 |
| `{embed(image):URL}`          | Set Main Image.                                                                                  |
| `{embed(thumb):URL}`          | Set Thumbnail.                                                                                   |
| `{embed(field):FieldOptions}` | Add a field. Inline is `true` or `false`. Available Field options are "Name", "Value", "Inline". |

**Example**:

```ts-tags theme={null}
{embed(title):User Info}
{embed(desc):Info about {user}}
{embed(field):ID|{user.id}|true}
{embed(field):Joined|Today|true}
{embed(color):#5865F2}
```

## String Manipulation

* **Slice**: `{slice(start, end):text}`

  ```ts-tags theme={null}
  {slice(0,5):Hello World} -> Hello
  ```

<Info>
  *Note: This reference covers the modules currently enabled in KaoriBot. With more to come in the future!*
</Info>