Crate hexavalent[][src]

Expand description

Write HexChat plugins in Rust.

To create your plugin:

  • Make a library crate with crate-type = "cdylib".
  • Define a type, e.g. struct MyPlugin, to hold any state your plugin needs.
  • Implement the Plugin trait for MyPlugin.
  • Call export_plugin with the type MyPlugin, its name, description, and version.

On Windows, it is recommended to add -C target-feature=+crt-static to your RUSTFLAGS, for example in <project root>/.cargo/config. This ensures that your DLL does not dynamically import the MSVCRT.


The following is a port of HexChat’s example “auto-op” plugin. It will automatically OP everyone who joins (so don’t try this if you’re in a real channel!), and can be toggled on and off with /autooptoggle.

use std::cell::Cell;
use hexavalent::{Plugin, PluginHandle, export_plugin};
use hexavalent::event::print::Join;
use hexavalent::hook::{Eat, Priority};

struct AutoOpPlugin {
    enabled: Cell<bool>,

impl Default for AutoOpPlugin {
    fn default() -> Self {
        Self {
            enabled: Cell::new(true),

impl AutoOpPlugin {
    fn autooptoggle_cb(&self, ph: PluginHandle<'_, Self>, _words: &[&str]) -> Eat {
        if !self.enabled.get() {
            ph.print("Auto-Oping now enabled!");
        } else {
            ph.print("Auto-Oping now disabled!");
        // eat this command so HexChat and other plugins can't process it

    fn join_cb(&self, ph: PluginHandle<'_, Self>, args: [&str; 4]) -> Eat {
        let [nick, _channel, _host, _account] = args;
        if self.enabled.get() {
            // op ANYONE who joins
            ph.command(&format!("OP {}", nick));
        // don't eat this event, HexChat needs to see it

impl Plugin for AutoOpPlugin {
    fn init(&self, ph: PluginHandle<'_, Self>) {
            "Usage: AUTOOPTOGGLE, turns OFF/ON Auto-Oping",
        ph.hook_print(Join, Priority::Normal, Self::join_cb);

        ph.print("AutoOpPlugin loaded successfully!");

    fn deinit(&self, ph: PluginHandle<'_, Self>) {
        ph.print("Unloading AutoOpPlugin...");

export_plugin!(AutoOpPlugin, "AutoOp", "Auto-Ops anyone who joins", "0.1");


In general, this library depends on HexChat invoking the plugin from only one thread. If that is not the case, this library provides no guarantees. (Although it is never explicitly stated that this is true, HexChat’s plugin documentation says nothing of synchronization, and none of the example plugins have any. It also seems true in practice.)

In debug mode (specifically, when debug_assertions is enabled), the current thread ID is checked every time the plugin is invoked, which can help detect misbehavior.


Server/channel contexts.

Print and server events.

Fake plugins.

Hook callbacks.

Context info.

Info lists.

Sending modes.

Global preferences.

String format stripping.


Defines the necessary exports for HexChat to load your plugin.


Interacts with HexChat’s plugin API.


Must be implemented by all HexChat plugins.