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

# Plugins

> What plugins are for, what they can and cannot do, and how to install one.

A plugin adds a feature to **Cordial**, not to Roblox. It can set your Discord
status from the game you are in, apply a set of FastFlags, send a desktop
notification, or carry a pack of replacement textures. It cannot run code
inside Roblox, read or change the game's memory, or give you a script
executor. Those abilities are not switched off in Cordial; they do not exist in
it at all, so no plugin and no fork can switch them on.

## How a plugin is kept in check

Each plugin is a separate program, written in TypeScript and run by
[Deno](https://deno.com) with every one of Deno's permissions turned off. It
cannot open files, use the network or start programs on its own. It asks
Cordial for things, and Cordial does them only if you allowed that kind of
request.

Those kinds of request are called **capabilities**. A plugin lists the ones it
wants, and starts with none of them granted. You grant them per profile, and
Cordial describes each one in plain words before you do.

<Accordion title="Every capability a plugin can ask for">
  | Capability | What it lets the plugin do |
  | - | - |
  | `flags.read` | See the FastFlags in effect and where each one came from |
  | `flags.write` | Set FastFlags of its own. They apply at the next launch, and your own `flags.json` still wins |
  | `log` | Write to Cordial's log |
  | `lifecycle.read` | Know when the client starts, which Roblox version it is, and when it stops |
  | `state.read` | Read which place, server and user the client is on |
  | `presence.set` | Set your Discord Rich Presence. Cordial talks to Discord, not the plugin |
  | `notify.send` | Show a desktop notification |
  | `url.open` | Open an `http` or `https` link in your browser |
  | `assets.override` | Point Cordial at a folder of replacement assets while running |
  | `settings.read`, `settings.write` | Keep its own settings, which Cordial stores for it |
  | `events.declare`, `events.publish`, `events.subscribe` | Exchange events with other plugins |
</Accordion>

<Note>
  A plugin never receives a network connection or a file. When it sets your
  Discord status, it hands Cordial the text and Cordial sends it.
</Note>

## The plugins that come with Cordial

| Plugin | What it does | On by default |
| - | - | - |
| **Discord presence** | Shows "Using Cordial", or the game's own status if the game provides one, in Discord | Yes, after you allow it |
| **Flag inspector** | Logs every FastFlag in effect and which file set it. Mostly an example to learn from | Yes, after you allow it |
| **FPS Flex** | Picks how frames are presented and caps the frame rate (60 to 240). Applies at the next launch | No: an uncapped frame rate costs heat and battery |
| **Hide the interface** | Unlocks Roblox's shortcuts for hiding the game's interface, for screenshots and videos | Yes, after you allow it |

The first time you open the **Plugins** page in a profile, Cordial asks once,
in a single dialog, for the capabilities the plugins that are switched on
need. Until you choose **Allow**, they do nothing. Choose **Not now** and use
the switches on each plugin's row to allow only some. A plugin that ships off
asks when you switch it on. Nothing is asked while you are on another page of
Settings. Why: [ADR-021](/adr/ADR-021-everything-is-a-plugin).

<Warning>
  **Hide the interface** works only for accounts in the Roblox group that
  unlocks those shortcuts (the one Bloxstrap uses). Cordial cannot check whether
  yours is.
</Warning>

## Install a plugin

There is no plugin store yet. A plugin reaches you as a file someone shares, or as a folder you are writing yourself.

<Steps>
  <Step title="Turn plugins on">
    Open **Settings → Plugins** and switch on **Use Plugins**. If Deno is not installed, the page offers a **Download** button (about 39 MB). A `deno` already on your system is used instead. See [Deno](/plugins#deno).
  </Step>

  <Step title="Install the archive">
    Under **Install from a file**, choose **Choose file…** and pick the plugin. You do not need a terminal and you do not need to know where plugins live.

    The file must be a `.tar.zst`. A `.tar.gz` is not a Cordial plugin archive, whatever is inside it, and the picker refuses it. Why: [ADR-014](/adr/ADR-014-plugin-registry-and-unpacking).
  </Step>

  <Step title="Switch it on and grant what it needs">
    The plugin appears under **Installed**, switched off, with the permissions it asks for listed. Nothing runs until you switch it on. Then turn on only the capabilities you are happy to give it.
  </Step>
</Steps>

Installing, updating, removing, enabling, disabling and granting reach a running game within a second or two, with no restart. FastFlags are the exception: they apply at the next launch.

To remove a plugin, use its **Remove** button. Built-in plugins cannot be removed, only switched off. If you are writing a plugin rather than installing one, you can [load its folder directly](/plugins#load-a-plugin-from-a-folder).

<Warning>
  **Trust the source.** A plugin runs as a real process on your machine. Cordial gives it no file access, network, environment or subprocess of its own, and every capability it uses is one you approved by name. That is a boundary, not a guarantee about intent. Installing something because a stranger linked it is the same decision it is anywhere else.
</Warning>

### Where plugins live

| Install | Folder |
| - | - |
| Flatpak | `~/.var/app/io.github.luohoa97.Cordial/data/cordial/plugins/` |
| Other installs | `~/.local/share/cordial/plugins/` |

Which plugins are switched on, and what each may do, is stored per profile, so two profiles can have different plugins on.

## Writing a plugin

See [Writing a plugin](/plugin-development) for a working plugin in five
minutes, and the [plugin API reference](/plugin-api) for every method and
event.

## What does not work yet

* **No plugin store.** The signed index format and its checks exist, but
  nobody runs an index, so there is nothing to browse.
* **FastFlags apply at the next launch.** A plugin cannot change a flag in a
  running game.
* **Two events are never sent.** `client.ready` and `window.resized` are
  declared but nothing publishes them yet, so a plugin waiting for them waits
  forever.
* **Plugins cannot draw anything** over the game or add buttons to Cordial's
  window.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.