> For the complete documentation index, see [llms.txt](https://docs.engar.party/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.engar.party/scripts/advanced.md). # advanced ## introduction Advanced scripts are based on the LUA programming language. You can find the basic syntax and usage at ## standard library Standard library provides a toolbox filled with pre-built functions and modules. | Entity | Description | Example | | ----------- | ----------------------------------- | ---------------------------- | | print | Prints to stdout | print{content="hello world"} | | table\_keys | Returns a list of table keys | table\_keys(some\_table) | | dir | Returns a list of entity attributes | dir(ctx) | | comma | Formats an integer with commas | comma(1000) -- 1,000 | | underscore | Formats an integer with underscore | underscore(10000) -- 10\_000 | ## random | Entity | Description | Example | | ------ | ------------------------- | ------------------------------ | | choice | Picks a random table item | random.choice({"a", "b", "c"}) | ## database #### Description The `Database` class provides methods for managing data stored in a database, such as saving, retrieving, and deleting key-value pairs #### Methods * `init(namespace: str = "public") -> Database`: Initializes the database with the specified namespace. * `save(key, value)`: Saves a key-value pair to the database. * `delete(key)`: Deletes a key-value pair from the database. * `get(key)`: Retrieves a value from the database based on the key. * `select_many(search, sort)`: Selects multiple key-value pairs from the database based on a search string. #### Properties * `set`: A property that aliases the `save` method. ## http *** ### Response #### Attributes * `status`: Returns the status code of the response. * `content_type`: Returns the content type of the response. * `content_length`: Returns the content length of the response. #### Methods * `to_file(data)`: Reads and returns the response content as a file.\ `filename`: File filename\ `description`: file description * `text()`: Reads and returns the response content as text. * `json()`: Reads and returns the response content as JSON. *** ### http #### Description The `HTTP` class provides methods for making HTTP requests. #### Methods * `get(url, data)`: Makes a GET request. * `post(url, data)`: Makes a POST request. *** #### Options data can contain headers, body params etc... ### Examples ```lua local http = import("http") -- Perform a GET request. response = http.get("https://example.com") -- GET request with headers response = http.get("https://example.com", {headers={Authorization="test"}}) --Perform a POST request response = http.post("https://example.com") ``` ## Discord Objects Here's the documentation for the `Discord` class: *** ### discord #### Description The `Discord` class provides methods to retrieve Discord entities such as users, messages, and channels, and also includes utilities for sending replies and creating embeds. #### Methods * `get_user(search)`: Retrieves a user by their name or ID. * `get_message(search)`: Retrieves a message by its ID or link. * `get_text_channel(search)`: Retrieves a text channel by its name or ID. * `get_voice_channel(search)`: Retrieves a voice channel by its name or ID. * `get_category_channel(search)`: Retrieves a category channel by its name or ID. * `reply()`: Marks the reply as a reference. * `Embed()`: Utility method to create an embed object. #### Properties * `getUser`: Alias for the `get_user` method. * `getMessage`: Alias for the `get_message` method. #### Example Usage ```lua user = discord.get_user("username") -- Retrieve a message by ID message = discord.get_message("message_id") -- Retrieve a text channel by name or ID text_channel = discord.get_text_channel("channel_name") -- Mark the reply as a reference discord.reply() -- Create an embed embed = discord.Embed{title="Embed Title", description="Embed Description"} ``` *** ### ctx.args #### Description The `Arguments` class manages the raw and parsed arguments passed to a command. It allows for retrieval, removal, and conversion of arguments. #### Methods * `str()`: Returns a string representation of the raw arguments. * `get(name)`: Retrieves an argument by name or index. * `__getitem__(name)`: Retrieves an argument by name using square bracket notation. * `remove(name)`: Removes an argument by name or index. * `to_dict()`: Converts the parsed arguments to a dictionary. #### Example Usage ```lua -- Access and manipulate raw arguments raw_args = ctx.args.str() print(raw_args) # Output: "arg1 arg2 arg3" -- Access parsed arguments parsed_arg = args.get("name") print(parsed_arg) -- Output: "value" -- Remove an argument removed_arg = args.remove("name") print(removed_arg) -- Output: "value" -- Convert parsed arguments to dictionary parsed_dict = args.to_dict() print(parsed_dict) -- Output: {"name": "value"} ``` *** ### ctx #### Description The `Context` class provides an encapsulation of the current context in which a command or interaction is executed. It includes information about the author, guild, and message, as well as methods for sending replies and reactions. #### Attributes * `author`: The user who initiated the interaction. * `guild`: The guild (server) where the interaction occurred. * `message`: The message object associated with the interaction. * `channel`: The channel where the interaction took place. #### Properties * `prefix`: The prefix used to trigger the command. * `trigger`: The trigger (command) that initiated the interaction. * `args`: The arguments object passed with the command. * `strargs`: A string representation of the arguments. * `add_reaction`: An alias for the `react` method. #### Methods * `react(emoji)`: Adds a reaction to the message associated with the context. * `send(data)`: Sends a message or embed as a reply to the interaction. * `reply(data)`: Sends a reply referencing the original message in the context. * `Ok(data)`: Sends a simple affirmative reply. #### Example Usage: ```lua -- Access context attributes author = ctx.author guild = ctx.guild message = ctx.message channel = ctx.channel -- Access context properties prefix = ctx.prefix trigger = ctx.trigger args = ctx.args strargs = ctx.strargs -- Send a message ctx.send("Hello, world!") -- Send an embed embed = Embed{title="Embed Title", description="Embed Description"} ctx.send(embed) -- Add a reaction ctx.react("👍") -- Reply to the original message ctx.reply("This is a reply.") -- Send an affirmative response ctx.Ok("Operation successful.") ``` *** ### user #### Description The `User` class represents a Discord user or member and provides access to various properties and methods to interact with them. #### Attributes * `name`: Returns the username of the user. * `tag`: Returns the discriminator of the user. * `display_name`: Returns the display name of the user. * `avatar`: Returns a string representing the URL of the user's avatar. * `id`: Returns the unique ID of the user. * `mention`: Returns a string mentioning the user. * `created_at`: Returns the timestamp of when the user's account was created. * `joined_at`: Returns the timestamp of when the user joined the guild. * `mutual_guilds`: Returns the number of mutual guilds with the bot (if applicable). * `roles`: Returns a list of role IDs that the user has. * `banner`: Returns a coroutine that retrieves the user's banner. * `public_flags`: Returns a list of public user flags. * `accent_color`: Returns the user's accent color. * `color`: Returns the user's color. * `global_name`: Returns the user's global name. * `system`: Returns whether the user is a Discord system user. * `status`: Returns the user's status. * `activity`: Returns the user's current activity (if applicable). * `premium_since`: Returns the timestamp of when the user started boosting the guild. * `top_role`: Returns the ID of the user's top role in the guild. * `nick`: Returns the user's nickname in the guild. * `mobile_status`: Returns the user's status on mobile. * `desktop_status`: Returns the user's status on desktop. * `web_status`: Returns the user's status on web. * `is_timed_out`: Returns whether the user is timed out. * `permissions`: Returns a dictionary of guild permissions for the user. #### Methods * `add_role(search: str)`: Asynchronously adds a role to the user. * `remove_role(search: str)`: Asynchronously removes a role from the user. * `has_permissions(*permissions)`: Checks if the user has the specified permissions. * `has_role(search: str)`: Asynchronously checks if the user has a specific role. #### Example Usage ```lua has_admin = user.has_role("Administrator") print("Is Admin: " .. tostring(has_admin)) -- Add a role to the user await user.add_role("Moderator") -- Check if the user has specific permissions has_manage_channels = user.has_permissions("manage_channels", "kick_members") print("Can Manage Channels and Kick Members: " .. tostring(has_manage_channels)) ``` *** ### guild #### Description The `Guild` class represents a Discord guild (server) and provides access to various properties and methods to interact with it. #### Attributes * `name`: Returns the name of the guild. * `icon`: Returns a string representing the URL of the guild's icon. * `splash`: Returns a string representing the URL of the guild's splash image. * `banner`: Returns a string representing the URL of the guild's banner image. * `id`: Returns the unique ID of the guild. * `created_at`: Returns the timestamp of when the guild was created. * `members`: Returns the total number of members in the guild. * `boosts`: Returns the number of boosts the guild has. * `boosts_level`: Returns the level of boosts the guild has. * `owner`: Returns a `User` object representing the owner of the guild. * `features`: Returns a list of features enabled for the guild. * `roles`: Returns a list of role IDs present in the guild. * `approximate_member_count`: Returns an approximate count of members in the guild. * `approximate_presence_count`: Returns an approximate count of online members in the guild. * `emojis`: Returns the number of emojis present in the guild. * `afk_timeout`: Returns the AFK timeout duration in seconds. * `large`: Returns whether the guild is considered "large" (has more than 250 members). * `humans`: Returns the number of human members in the guild. * `bots`: Returns the number of bot members in the guild. * `joins`: Returns the number of members that joined the guild today. * `system_channel`: Returns a `Channel` object representing the system channel of the guild (if available). * `rules_channel`: Returns a `Channel` object representing the rules channel of the guild (if available). * `vanity_url`: Returns the vanity URL of the guild. * `vanity_url_code`: Returns the vanity URL code of the guild. * `verification_level`: Returns the verification level of the guild. * `mfa_level`: Returns the MFA (Multi-Factor Authentication) level required for the guild. * `nsfw_level`: Returns the NSFW (Not Safe For Work) level of the guild. *** *** ### attachment #### Description The `Attachment` class represents a file attached to a message and provides access to various properties related to the attachment. #### Attributes * `url`: Returns the URL of the attachment. * `content_type`: Returns the content type of the attachment. * `filename`: Returns the filename of the attachment. * `proxy_url`: Returns the proxy URL of the attachment. * `description`: Returns the description of the attachment. * `id`: Returns the unique ID of the attachment. #### Example Usage ```lua print(attachment.url) print(attachment.filename) ``` *** ### emoji #### Description The `Emoji` class represents a custom emoji and provides access to various properties related to the emoji. #### Attributes * `name`: Returns the name of the emoji. * `id`: Returns the unique ID of the emoji. * `created_at`: Returns the timestamp of when the emoji was created. * `url`: Returns the URL of the emoji. * `is_usable`: Returns whether the emoji is usable. * `managed`: Returns whether the emoji is managed. * `available`: Returns whether the emoji is available. * `animated`: Returns whether the emoji is animated. * `require_colons`: Returns whether the emoji requires colons. #### Example Usage ```lua print(emoji.name) print(emoji.url) ``` *** ### reaction #### Description The `Reaction` class represents a reaction to a message and provides access to various properties related to the reaction. #### Attributes * `emoji`: Returns the Emoji object representing the emoji of the reaction. * `is_custom_emoji`: Returns whether the reaction emoji is custom. * `count`: Returns the count of users who reacted with the emoji. #### Example Usage ```lua print(reaction.emoji) print(reaction.count) ``` *** ## message #### Description The `Message` class represents a message in a channel and provides access to various properties related to the message. #### Attributes * `id`: Returns the unique ID of the message. * `content`: Returns the content of the message. * `author`: Returns the User object representing the author of the message. * `channel`: Returns the Channel object representing the channel the message was sent in. * `guild`: Returns the Guild object representing the guild the message was sent in. * `jump_url`: Returns the jump URL of the message. * `type`: Returns the type of the message. * `pinned`: Returns whether the message is pinned. * `created_at`: Returns the timestamp of when the message was created. * `edited_at`: Returns the timestamp of when the message was last edited (if applicable). * `reactions`: Returns a list of Reaction objects representing reactions to the message. * `embeds`: Returns a list of dictionaries representing embeds in the message. * `attachments`: Returns a list of Attachment objects representing attachments in the message. * `files`: Alias for `attachments`. #### Example Usage ```lua -- Access message properties print(message.content) print(message.author) print(message.channel) -- Check if the message is pinned if message.pinned then print("This message is pinned.") end ``` *** ### embed A class representing an embed object in Discord. **Methods:** * `add_field()`: * Parameters: * `data`- Data for adding a field to the embed.\ `name`- Field name\ `value`- Field value\ `inline`- true or false, should field be inline or not. * Adds a field to the embed. * `set_footer()`: * Parameters: * `data`- Data for setting the footer of the embed.\ `text`- Footer text\ `icon_url`- A valid image URL for footer icon * Sets the footer of the embed. * `set_author()`: * Parameters: * `data`- Data for setting the author of the embed.\ `name`- Author name\ `icon_url`- A valid image URL for author icon\ `url`- A valid URL for author url * Sets the author of the embed. * `set_title()`: * Parameters: * `title` - The title of the embed. * Sets the title of the embed. * `set_description()`: * Parameters: * `description`- The description of the embed. * Sets the description of the embed. * `set_color(self)`: * Parameters: * `color`- The color of the embed in hexadecimal format. * Sets the color of the embed. * `set_image()`: * Parameters: * `url`- The URL of the image to be displayed in the embed. * Sets the image of the embed. * `set_thumbnail()`: * Parameters: * `url`- The URL of the thumbnail to be displayed in the embed. * Sets the thumbnail of the embed. * `set_timestamp()`: * Parameters: * `timestamp` - Unix timestamp for the embed's timestamp. If `None`, no timestamp will be used. * Sets the timestamp of the embed. * `copy()`: * Creates a copy of the embed object. * `to_dict():` * Converts the embed object into a dictionary. **Properties:** * `timestamp`: * Returns the timestamp of the embed. ## interaction #### Description The `Interaction` class represents an interaction with a Discord component (e.g., a button click or a select menu interaction) and provides methods to access interaction data. #### Attributes * `guild`: Returns the guild associated with the interaction. * `user`: Returns the user who initiated the interaction. * `channel`: Returns the channel where the interaction occurred. * `message`: Returns the message associated with the interaction. * `value`: Returns the value of the interaction. * `custom_id`: Returns the custom ID of the interaction. #### Methods * `not_ephemeral()`: Marks the interaction response as not ephemeral. * `options(value)`: Returns the value of the specified option in the interaction. #### Example Usage ```lua print(interaction.custom_id) print(interaction.guild) print(interaction.user) print(interaction.channel) print(interaction.message) print(interaction.value) -- Get the value of a specific option option_value = interaction.options("option_name") print("Option Value: " .. tostring(option_value)) -- Mark the interaction response as not ephemeral interaction.not_ephemeral() ``` *** ## selectoption A class representing an option for a select menu. **Options:** * `label`- The label text of the option. * `description`- The description text of the option. * `emoji`- The emoji associated with the option. * `default`- Indicates if the option is selected by default. ## selectmenu A class representing a select menu. **Options:** * `type`: `int` - Specifies the type of the select menu. Possible values: * `3`: String Select * `5`: User Select * `6`: Role Select * `7`: Mentionable Select * `8`: Channel Select * `placeholder`- The placeholder text for the select menu. * `row`- The row in which the select menu should be displayed. * `disabled`- Indicates whether the select menu is disabled or not. * `min_values`- The minimum number of options that can be selected. * `max_values`- The maximum number of options that can be selected. ## button A class representing a button element. **Options:** * `custom_id`- The custom ID of the select menu or button. * `disabled`- Indicates whether the button is disabled or not. * `label`- Label text for button * `style`- Color style for button, can be "grey" "green" "red" "blurple" * `url` - URL address for button optionally if you want the button to redirect to certain website instead of executing a function. *** ### channel #### Description The `Channel` class represents a Discord channel and provides access to various properties and methods to interact with it. #### Attributes * `name`: Returns the name of the channel. * `id`: Returns the unique ID of the channel. * `mention`: Returns a string mentioning the channel. * `position`: Returns the position of the channel. * `type`: Returns the type of the channel. * `created_at`: Returns the timestamp of when the channel was created. * `nsfw`: Returns whether the channel is marked as NSFW. * `topic`: Returns the topic of the channel (if applicable). * `parent`: Returns the parent category of the channel (if applicable). #### Methods * `is_nsfw()`: Checks if the channel is marked as NSFW. #### Example Usage ```lua -- Access channel properties print(channel.name) print(channel.id) print(channel.type) -- Check if the channel is NSFW if channel.is_nsfw() then print("This channel is NSFW.") end parent_category = channel.parent if parent_category then print("Parent Category: " .. tostring(parent_category)) end ```