{"id":18772708,"url":"https://github.com/vyfor/cordex","last_synced_at":"2025-08-01T13:39:32.470Z","repository":{"id":190008039,"uuid":"681682310","full_name":"vyfor/Cordex","owner":"vyfor","description":"🚀 A fast, powerful and easy-to-use Javacord framework.","archived":false,"fork":false,"pushed_at":"2024-05-27T15:40:49.000Z","size":255,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-02T13:13:14.447Z","etag":null,"topics":["bot","command","cordex","discord","framework","java","javacord","kotlin","reflection"],"latest_commit_sha":null,"homepage":"https://discord.gg/mw27xdA3wh","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vyfor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-22T14:26:58.000Z","updated_at":"2025-01-16T00:37:45.000Z","dependencies_parsed_at":"2023-08-22T21:46:18.779Z","dependency_job_id":"cb398b88-a236-456a-a31b-aea7e57eebf3","html_url":"https://github.com/vyfor/Cordex","commit_stats":{"total_commits":92,"total_committers":2,"mean_commits":46.0,"dds":0.05434782608695654,"last_synced_commit":"11d96eef369f817bced4e047f2e3dbb78b38266a"},"previous_names":["reblast/cordex","vyfor/cordex"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/vyfor/Cordex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyfor%2FCordex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyfor%2FCordex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyfor%2FCordex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyfor%2FCordex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vyfor","download_url":"https://codeload.github.com/vyfor/Cordex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyfor%2FCordex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268232840,"owners_count":24217344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","command","cordex","discord","framework","java","javacord","kotlin","reflection"],"created_at":"2024-11-07T19:29:58.576Z","updated_at":"2025-08-01T13:39:32.431Z","avatar_url":"https://github.com/vyfor.png","language":"Kotlin","readme":"# 🧩 Cordex [![Kotlin](https://img.shields.io/badge/Kotlin-1.9.0-blue.svg?style=flat\u0026logo=kotlin)](https://kotlinlang.org) [![](https://jitpack.io/v/vyfor/Cordex.svg)](https://jitpack.io/#vyfor/Cordex)\n\n**🚀 A fast, powerful and easy-to-use [Javacord](https://javacord.org/) framework written in [Kotlin](https://kotlinlang.org/).**\n\n**Cordex** is an innovative command framework designed to optimize the capabilities of Javacord, combining rich features and an intuitive syntax that simplifies the process of building Discord bots.\nIt presents a developer-friendly solution for defining command arguments in a manner reminiscent of command-line interfaces (CLI).\n\n\u003e [!WARNING]\n\u003e Keep in mind that this library is in beta, and may not be ready for production purposes just yet.\n\n## 🔌 Requirements\n\nIn order to use Cordex, you'll need the following prerequisites:\n\n- **Java**: `8 or later`\n- **Kotlin**: `1.9.0`\n- **Coroutines**: `1.7.3`\n- **Javacord**: `3.9.0`\n\n## 📦 Installation\n\n### Gradle\n\n```gradle\nrepositories {\n    ...\n    maven(\"https://jitpack.io\")\n}\n\ndependencies {\n    implementation(\"com.github.vyfor:Cordex:0.3.2\")\n}\n```\n\n### Maven\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003ejitpack.io\u003c/id\u003e\n        \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.vyfor\u003c/groupId\u003e\n    \u003cartifactId\u003eCordex\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## ✨ Examples\n\n### Setting up Cordex\n\nInitialize Cordex by setting your bot token. You can configure the created DiscordApiBuilder inside the `api` block.\n\n```kt\nfun main() {\n  cordex(\"TOKEN\") {\n    prefix { \"~\" }\n    \n    api {\n      setAllIntents()\n    }\n  }\n}\n```\n\n### Creating a Command\n\nThere are two ways of creating commands:\n1. **Through inheritance:**\n    - Define a custom command by extending the `Command` class and implementing its execute function.\n    ```kt\n    class ExampleCommand : Command(\"example\") {\n      override suspend fun Arguments.execute(ctx: Context) {\n        // Command logic goes here\n        ctx.message.reply(\"This is an example command!\")\n      }\n    }\n    ```\n2. **Through the DSL function:**\n    - Define a custom command by using the `command()` function and providing necessary fields.\n    ```kt\n    command(\"example\") {\n      execute { ctx -\u003e\n        ctx.message.reply(\"This is an example command!\")\n      }\n    }\n    ```\n\n#### Registering a text command\n\nAdd your newly created command to the command registry using the following methods:\n- A plus sign followed by an instance of your command class.\n- The `load(\"package\")` method to load classes extending the `Command` class.\n\n```kt\ncordex(\"TOKEN\") {\n  //...\n  \n  commands {\n    +ExampleCommand()\n    \n    load(\"me.blast.commands\")\n  }\n}\n```\n\n\u003e [!WARNING]\n\u003e Specifying a package name isn't mandatory, but highly recommended. Not doing so may negatively impact the startup overhead of the bot.\n\n### Error Handling\n\nCordex offers robust error handling capabilities to ensure your bot can gracefully manage unexpected situations.\n\n#### Command execution error\n\nUse `onError` to define how your bot responds when an exception occurs during command execution. \n\n```kt\ncordex(\"TOKEN\") {\n  onError { event, command, ex -\u003e\n    // Error handling logic goes here\n    event.message.reply(\"Error!\")\n  }\n}\n```\n\n#### Argument parsing error\n\nCordex defaults to sending a usage message on argument parsing errors. However, you can customize this behavior with your own function using `onParseError`:\n\n```kt\ncordex(\"TOKEN\") {\n  onParseError { event, command, ex -\u003e\n    // Error handling logic goes here\n    event.message.reply(\n      when (ex) {\n        is ArgumentException.Invalid -\u003e \"Invalid value provided for argument ${ex.argument.argumentName}\"\n        is ArgumentException.Empty -\u003e \"No value provided for argument ${ex.argument.argumentName}\"\n        is ArgumentException.Insufficient -\u003e \"Insufficient amount of values provided for argument ${ex.argument.argumentName}\"\n        is ArgumentException.Missing -\u003e \"Missing required arguments: ${ex.arguments.joinToString(\", \") { it.argumentName }}\"\n      }\n    )\n  }\n}\n```\n\n### Command Arguments\n\n\u003e Cordex follows the approach of handling arguments in a way similar to how command-line interfaces (CLI) do.\n\n**There exist 3 types of arguments:**\n- **Options**\n  - Options are arguments capable of accepting values.\n- **Flags**\n  - Flags are arguments that are optional, and providing them assigns their value as true.\n- **Positional arguments**\n  - Positional arguments are arguments provided without explicit naming.\n\nYou can define each of these argument types using their respective functions:\n\n```kt\nclass ExampleCommand : Command(\"example\") {\n  val option by option(\"Description\") // --option, -o \u003cvalue\u003e\n  val flag by flag(\"Description\") // --flag, -f\n  val positional by positional(\"Description\") // [--positional] \u003cvalue\u003e\n}\n```\n\nNames are optional; Cordex obtains them from variable names, using the first letter as the short name.\n\n#### Accessing argument values\n\nArgument values can be accessed in different ways:\n1. `option.value`\n2. `option()`\n3. `option { it -\u003e ... }`\n \n### Beyond the Basics\n\nArguments may be optional, hold default values, accept multiple values, and have validators:\n\n```kt\nval name by option().multiple(1..2) // List\u003cString\u003e (min: 1, max: 2)\nval age by option().optional(18) { toInt() } // Int? (default: 18)\n```\n\nValidators also offer the capability to include custom error messages, achieved by throwing an exception with a message included.\n\n### Predefined validators\n\nCordex provides a range of predefined validators you can utilize:\n\n#### Primitive types\n- `int()` `uInt()`\n- `long()` `uLong()`\n- `float()`\n- `double()`\n\n#### Discord entities\n- `user()`\n- `role()`\n- `category()`\n- `message()`\n- `customEmoji()`\n- `snowflake()`\n- `textChannel()` `voiceChannel()` `threadChannel()` `stageChannel()` `forumChannel()` `channel(types...)`\n\n#### And more\n- `url()`\n- `duration()`\n- `date()`\n- `dateTime()`\n- `color()`\n- `unicodeEmoji()`\n- `enum()`\n- `map()`\n\n\u003e [!NOTE]\n\u003e These methods combine multiple input values (from multi-value arguments) into a single string and try to convert the combined result to the appropriate type.\n\u003e \n\u003e If you want each input value to be converted separately, use the same function with a plural name. *e.g.* `users()` `roles()` \n\n### Command Suggestions\n**Cordex** offers a feature known as command suggestions, allowing the bot to proactively suggest commands that closely match any incorrectly provided by the user.\n\nTo enable this functionality, simply include the following line of code:\n```kt\ncordex(\"TOKEN\") {\n  enableCommandSuggestion(DistanceAccuracy)\n}\n```\nHere, the parameter `DistanceAccuracy` represents the level of precision in matching input string with defined commands.\n\n### Pagination\nYou can create a paginator that goes through a given list using the `List\u003cT\u003e.paginate` or `List\u003cT\u003e.paginateDefault` function.\nThe `paginateDefault` function provides the same pagination features but with default handlers attached.\n\nThe syntax is as follows:\n```kt\nList\u003cT\u003e.paginate(\n  channel = ctx.channel,\n  messageEvent = ctx.event,\n  itemsPerPage = 1,\n  onStart = { messageEvent, paginator, currentItems -\u003e  \n    MessageBuilder().setContent(currentItems.joinToString(\"\\n\"))\n  },\n  onPagination = { message, paginator, currentItems -\u003e\n    MessageUpdater(message).setContent(currentItems.joinToString(\"\\n\"))\n  },\n  onEmpty = {\n    MessageBuilder().setContent(\"No items found\")\n  },\n  removeAfter = 2.minutes,\n  canClose = true // Adds a button to close the paginator\n)\n```\n\n\u003e Take a look at [PaginationUtils.kt](src/main/kotlin/me/blast/utils/pagination/PaginationUtils.kt) to see a complete example.\n\n### Command Interceptors\nAs the name suggests, command interceptors intercept a command's execution and run the given block of code.\nThe block must return a boolean value, indicating whether to continue the execution or not.\n\n```kt\ncordex(\"TOKEN\") {\n  intercept(\"refresh\") { event, command -\u003e\n    event.server.get().id == 0123456789L\n  }\n}\n```\n\n## 📚 Dependencies\n**Cordex relies on these amazing libraries:**\n  - https://github.com/Javacord/Javacord\n\n    An easy to use multithreaded library for creating Discord bots in Java.\n\n  - https://github.com/felldo/JEmoji\n\n    Java Emoji (JEmoji) is a lightweight fast emoji library for Java with the purpose to improve and ease working with emojis\n\n## 📝 TODO\n[ ] Slash command support\n[ ] `Attachment` argument type\n[ ] Command categorization\n[ ] Subcommands\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyfor%2Fcordex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvyfor%2Fcordex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyfor%2Fcordex/lists"}