> For the complete documentation index, see [llms.txt](https://mythicalbot.gitbook.io/arklynn-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mythicalbot.gitbook.io/arklynn-docs/resources/scripting.md).

# Scripting

{% hint style="warning" %}
*(Legacy options are not covered here.)*\
\
We recommend using our [**embed builder**](https://arklynn.xyz/embed) instead of scripting the embeds manually as it is easier
{% endhint %}

***

### 1. Script Syntax Basics

#### Variables

Variables are placeholders that are replaced with real data when the message is sent.\
They are written inside curly braces: `{variable}`.

**Common Variables Available in All Announcements**

| Variable              | Description                                       |
| --------------------- | ------------------------------------------------- |
| `{user}`              | Full user tag (name#discriminator)                |
| `{user.name}`         | Username only                                     |
| `{user.mention}`      | Mention the user                                  |
| `{user.id}`           | User's Discord ID                                 |
| `{user.avatar}`       | URL to user's avatar                              |
| `{guild.name}`        | Server name                                       |
| `{guild.count}`       | Total member count                                |
| `{guild.id}`          | Server ID                                         |
| `{guild.icon}`        | Server icon URL                                   |
| `{guild.boost_count}` | Number of boosts (for Booster event)              |
| `{timestamp}`         | Current timestamp (adds a timestamp to the embed) |

{% hint style="info" %}
**Note:** Some events may have additional variables (e.g., `{level}` for levelup). See the event‑specific sections below.
{% endhint %}

#### Separator: `$v`

Use `$v` to separate different parts of your script:

* Between plain content and an embed
* Between embed fields
* Between an embed and a button

#### Building an Embed

To create an embed, start with `{embed}` and then add fields separated by `$v`.

**Available Embed Fields:**

| Field         | Format                                                       | Example                                   |
| ------------- | ------------------------------------------------------------ | ----------------------------------------- |
| `color`       | `{color: #hexcode}`                                          | `{color: #ff9900}`                        |
| `title`       | `{title: Your title}`                                        | `{title: Welcome!}`                       |
| `description` | `{description: Text here}`                                   | `{description: Hello {user.name}!}`       |
| `field`       | `{field: Name && Value && inline}` (inline = `true`/`false`) | `{field: Level && {level} && true}`       |
| `thumbnail`   | `{thumbnail: image_url}`                                     | `{thumbnail: {user.avatar}}`              |
| `author`      | `{author: name && icon_url}` (icon\_url optional)            | `{author: {guild.name} && {guild.icon}}`  |
| `footer`      | `{footer: text && icon_url}` (icon\_url optional)            | `{footer: Thanks for joining!}`           |
| `image`       | `{image: image_url}`                                         | `{image: https://example.com/banner.png}` |
| `timestamp`   | `{timestamp}` (no value)                                     | `{timestamp}`                             |

#### Adding a Button

Buttons are defined with:

text

```
{button: link && Label && https://url}
```

* **type** – currently only `link` (opens a URL).
* **label** – text shown on the button.
* **url** – the full URL (must start with `https://` or `http://`).

Place the button after your embed or content, separated by `$v`.

***

### 2. Examples 

#### Example 1: Booster Announcement with Button

```
{embed}$v{color: #e2e8f0}$v{description: Thx [**{user.name}**](https://discord.com/users/{user.id}), for boosting :coraao:}$v{thumbnail: {user.avatar}}$v{author: {guild.name} @ {guild.boost_count} boosts && {guild.icon}}$v{button: link && Check Boost Perks && https://discord.com/channels/...}
```

**Result:** An embed thanking the booster, with a button linking to perks.

#### Example 2: Levelup with Field and Footer

```
{embed}$v{color: #9b59b6}$v{title: New Level!}$v{description: {user.name} just advanced to level **{level}**!}$v{field: XP && {xp} && true}$v{footer: Keep it up!}
```

{% hint style="success" %}
More examples can be found on [our templates page.](https://arklynn.xyz/embed/templates)
{% endhint %}

***

### 3. Tips & Best Practices

* **Always test your scripts** in a private channel before enabling them publicly.
* **Use `$v` consistently** between every component (content, each embed field, button).
* **Keep URLs valid** – for button links, use full `https://` addresses.
* **Don't over‑complicate** – sometimes a simple embed is more effective than a crowded one.
* **Use variables to personalize** – users appreciate seeing their own name and avatar.
* **Check permissions** – if you include a button linking to a channel, ensure the link is correct and users have access.

***

### 4. Troubleshooting

| Problem                | Likely Cause                                       | Solution                                                                                           |
| ---------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Embed not showing      | Missing `{embed}` or incorrect field syntax        | Ensure `{embed}` is the first part of the embed section and each field starts with `{field: ...}`. |
| Variables not replaced | Misspelled variable or not available in this event | Double‑check the variable name. Some variables are only for specific events.                       |
| Button doesn't appear  | Wrong button syntax or missing `$v`                | Use `{button: link && Label && https://url}` and separate with `$v`.                               |
| Message is blank       | Possibly no content or embed fields                | At least one part (content or embed) must be present.                                              |
| Colors not working     | Hex code missing `#` or invalid                    | Use a valid hex code with `#` (e.g., `#ff0000`).                                                   |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mythicalbot.gitbook.io/arklynn-docs/resources/scripting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.