Scripting with .hex

Overview

HexDroid keeps the app itself tiny with a script interpreter, a UI renderer, and the crypto primitives, and letting behaviour arrive as user-loadable .hex scripts. A script can react to incoming messages, add slash-style commands, call out to the web, schedule work, and even paint a full interactive screen.

The language is small and mIRC-flavoured, but it is its own thing. If you have written an mIRC remote or an aliases file before, most of this will feel familiar; if not, the examples below are enough to start from scratch.

Scripts are in Menu > Scripts. The bundled scripts shipped with HexDroid are disabled by default, you opt them in. You can also paste, import, edit, and revert scripts from there; see Installing & editing.

Anatomy of a script

A .hex file is a flat list of two kinds of block:

• on <event> { … }, an event handler that runs when something happens.
• alias <name> { … }, a reusable command you can call from anywhere (and that the user can run as /name).

Inside a block, statements are separated by a newline or a pipe |. Comments start with ; and run to the end of the line.

; greeter.hex, answer when someone mentions you
on TEXT {
  if ($contains($text, $me) == true) {
    msg $chan hi $nick, you mentioned me     ; newline or | separates statements
  }
}

alias wave { me waves at $1- }                ; usable as: /wave everyone

That is the whole shape of it: handlers react to events, aliases package up commands, and statements do the work. Everything else on this page is the vocabulary, the events you can hook, the variables you can read, the commands and functions you can call, and the view DSL for drawing screens.

Events

An on <event> block registers a handler. Event keys are case-insensitive.

Capabilities raise signals too: the encrypted transport delivers messages as on SIGNAL:age_msg and dealt secrets as on SIGNAL:age_deal (see Encrypted transport). The same on SIGNAL:… form handles them.

The TEXT pipeline

Inside on TEXT you can change what the user actually sees:

• rewrite <new text>, replace the line's text (e.g. to strip or annotate it).
• halt, stop processing and drop the line entirely.

on TEXT {
  if ($contains($text, "spoiler") == true) { halt }   ; hide spoilers
  rewrite $replace($text, ":wave:", "👋")       ; expand a shortcode
}

In on INPUT they act on your own line before it goes anywhere: rewrite changes what is sent, and halt stops it being sent at all. Test $iscmd to leave /commands alone:

on INPUT {
  if ($iscmd == true) { return }                        ; leave /commands alone
  if ($contains($text, "hunter2") == true) {            ; never send this by accident
    echo $chan *** not sent: that looks like your password
    halt
  }
  rewrite $replace($text, ":shrug:", "🤷")       ; expand a shortcode before it's sent
}

The same two statements work in on ACTION, on INPUT and on NUMERIC. In a NUMERIC handler, halt hides the line only, the client still acts on it internally, so dropping an end-of-MOTD or an error numeric changes nothing but the display:

on NUMERIC {
  if ($whois != true) { return }  ; leave the same codes alone outside a WHOIS
  if ($code == 344) { halt }     ; 344 RPL_WHOISCOUNTRY, don't want it
  if ($code == 350) { halt }     ; 350 RPL_WHOISISWEBIRC
}

An optional glob filter narrows an event: on TEXT:*help* only runs when the text matches. Channel events (JOIN, PART, KICK, MODE, the status events, BAN/UNBAN, RAWMODE, TOPIC and INVITE) filter on the channel instead, so on JOIN:#help runs only for that channel. Everything else filters on the text, so filter a numeric by testing $code in the body as above.

Headers pasted from mIRC work too: on *:TEXT:*hello*:#:{ is read as <level>:<event>:<match>:<target>:. The level (and prefixes such as @ or !) is ignored, since HexDroid has no user levels. The match text works like a filter and may contain spaces and braces; with a $ in the level it's a regex instead, as in on $*:TEXT:/^!seen (\S+)/i:#:{ or on $*:TEXT:/^\d{3}$/:#:{. The target is # for channels, ? for private messages, * for both, or a comma list such as #help,#dev. on *:SIGNAL:name: and on *:START: work too, as on SIGNAL:name and on LOAD. A handler for an event HexDroid never raises is reported in the script log when the script loads, rather than silently never running.

The IRC events only fire for live traffic, never for history replayed after a reconnect, so a bouncer's backlog doesn't greet everyone again. They report what happened; unlike TEXT, they can't rewrite or halt it:

on CONNECT { msg NickServ IDENTIFY %ns_pass }         ; identify as soon as you connect

on JOIN:#help {
  if ($isme == true) { return }
  notice $nick Welcome to #help, $nick. Ask away, someone will answer.
}

on NOTICE {
  if ($nick == NickServ && $contains($text, "You are now identified") == true) { join #private }
}

Variables & arguments

Global variables, %name

Variables prefixed with % hold strings, numbers, lists, or maps, and keep their value between events until the scripts are reloaded. They are shared by every loaded script and by every network: two scripts that both set %ep overwrite each other, and whichever on LOAD runs last wins. Give a script's settings a prefix of their own (%img_ep, %tr_ep).

Built-in fields, $field

Inside a handler, these read-only fields describe the event:

Positional arguments, $1, $2-

When you call an alias, or raise a signal with extra words, or attach args to a view button, those words bind to numbered arguments:

Expansion is recursive: %vars, $fields, and $func(…) calls can all be nested inside each other.

alias greet {
  set -l %who $1                    ; first argument, local to this call
  msg $chan Hello %who, and also $2-   ; mix args, vars, and rest
}

Commands

A statement is a command followed by arguments. User aliases are commands too, and a fixed set of IRC commands can be run as well (see below).

Value functions

Functions are written $name(arg, arg, …) and return a value you can use anywhere a value is expected.

Strings & math

Lists & maps

Control flow

Conditions live in parentheses and combine with && and ||. Comparisons support ==, !=, <, >, <=, >=, plus isin (substring) and iswm (wildcard match).

if ($nick == ChanServ) {
  ; ignore services
} elseif (%warned > 3 && $isme == false) {
  msg $chan settle down
} else {
  inc %warned
}

foreach %p $keys(%score) {
  echo $chan %p has $get(%score, %p) points
}

while ($len(%queue) > 0) {
  ; ... process and shrink %queue ...
}

foreach <item> <collection> walks a list or a map's keys. halt stops the whole handler; return exits the current alias (optionally with a value).

HTTP & timers

Web requests are asynchronous: you name a signal to receive the result, plus any context words you want passed along.

Reloading scripts cancels everything still pending: a timer, request or file pick started before the reload never answers afterwards, so an edited script never receives its previous copy's callbacks.

; http.get  [flags] <url> <signal> [context...]
; http.post [flags] <url> <body> <signal> [context...]
http.post https://libretranslate.example/translate q=$urlencode($text)&source=auto&target=en done $chan

Flags go before the URL:

Flag values are read before argument expansion, so a %var in one arrives as that variable's whole value rather than the words the argument splitter would otherwise break it into. That is what makes -b the way to send JSON: the positional body is a single space-delimited word, so anything containing a space has to come through -b. A header value with spaces in it (a bearer token, say) goes the same way.

set %auth Authorization: Bearer $2
set %payload $tojson($map(text, $1-, lang, irc))
http.post -t application/json -h %auth -b %payload https://paste.example/api done $chan

Without -t, the content type is inferred from the body: one starting { or [ is sent as JSON, one shaped like key=value&key=value is sent form-urlencoded, and anything else goes as text/plain.

In the receiving handler, the response is available through these fields, and $json(body, path) pulls a value out of a JSON reply:

on SIGNAL:done {
  if ($httpok == true) {
    echo $1 ↳ $json($httpbody, translatedText)   ; $1 = the buffer we passed as context
  }
  else { echo $1 *** request failed ($httpstatus) $httperror }
}

Picking & uploading files

A script has no filesystem access and cannot name a path. The only way it sees a file is if you hand it one:

; media.pick   [-m <mime>] <signal> [context...]
; media.upload [-h <name:value>] [-p <name=value>] [-f <field>] [-r] <url> <token> <signal> [context...]
media.pick -m image/* picked $chan

media.pick does not open anything by itself. HexDroid shows a prompt naming the channel and network the script is running in, and only if you agree does the system file picker appear. The script is then handed a token for that one file, never a path, and can reach nothing else on the device. The pick's signal goes only to the script that asked, and only that script can upload with the token. Tokens last until scripts are reloaded.

media.upload sends the file to the URL without the bytes ever passing through the script. It POSTs multipart/form-data under field name file by default; -f <field> renames the field, -p <name=value> adds a text form field beside the file (repeatable, for an endpoint's own options), and -r sends the raw bytes as the request body instead, which is what a soju-style filehost wants. The body is prepared first so the request carries an exact Content-Length, which servers that read uploads by length (PHP among them) need. Files over 64 MB are refused. The reply carries the same fields an http.post does, $httplocation and $httperror included.

alias img { media.pick -m image/* picked $chan }

on SIGNAL:picked {
  if ($mediaok != true) { return }
  toast Uploading $medianame
  media.upload https://paste.example/img $mediatoken done $1
}

on SIGNAL:done {
  if ($httpok != true) { echo $1 upload failed ($httpstatus) $httperror | return }
  set -l %url $trim($httplocation)
  if ($len(%url) == 0) { set -l %url $trim($httpbody) }
  msg $1 %url
}

Redirects are not followed, so an endpoint answering with a 301 to a trailing slash or to an index.php reports that 301 rather than uploading. The error names where it wanted to send you, and that address is the one to use.

Check the body even on a 2xx: many upload endpoints answer 200 with JSON that describes a failure, so $httpok alone does not mean the file was stored.

Note there is no empty-string literal in .hex: %url == "" compares against a two-character string and is never true for a blank value. Test emptiness with $len(%url) == 0.

Interactive views

A view { … } block describes a screen using a small layout DSL, then mounts it. Rebuild and re-mount it whenever your state changes to "redraw". Buttons report taps back as signals, so a view plus a few on SIGNAL handlers is a complete little app.

Elements

Modifiers

Any element takes trailing modifiers: bold, fill, wrap (on a row, flow children onto extra lines instead of overflowing), circle, color <hex>, bg <hex>, bgimage <url>, gradient linear:<a>:<b>, textsize <sp>, width/height/size/radius <dp>, pad/gap <dp>, weight <n>, align <where>, border <hex> [w], offsetx/offsety <dp>, and elevation <dp>. On an image, the scale mode is crop (the default), fit, or stretch.

alias counter_render {
  view {
    surface bg #13243f radius 20 pad 16 {
      column gap 12 align center {
        text Counter bold color #ffffff textsize 18
        text %n color #8fd0ff textsize 40
        row gap 10 {
          button "-1" dec weight 1
          button "+1" inc weight 1
        }
        button "Reset" reset fill
      }
    }
  }
}

on LOAD          { set %n 0 }
on SIGNAL:inc    { inc %n | counter_render }
on SIGNAL:dec    { dec %n | counter_render }
on SIGNAL:reset  { set %n 0 | counter_render }

Encrypted transport (advanced)

Scripts that need to talk to other players or peers can use the age.* capability, the same Ed25519 + X25519 machinery behind +AGE. It provides identity (age.me), randomness and hashing (age.rand, age.sha), sending over a keyed channel (age.send), local loopback for solo/practice play (age.local), and sealing a secret to one recipient (age.seal). Inbound traffic arrives as on SIGNAL:age_msg (and dealt secrets as on SIGNAL:age_deal).

For running a table: age.host keys a channel as its host, $age.ready(chan) says whether it's keyed yet, $age.owner(chan) is the elected host (the lowest fingerprint present, the same on every client), and $age.members(chan) lists the other +AGE members present. age.close and age.purge tear a table down. The transport also raises on SIGNAL:age_peer when someone announces themselves on a channel, on SIGNAL:age_ready when a channel becomes keyed, and on SIGNAL:age_left when a member leaves by part, quit or kick ($from is their fingerprint, or yours when you leave or lose the connection).

The complete on-the-wire format, encoding, key derivation, sealed invites, the signed channel layer, and the 1:1 handshake and double ratchet, is published in the age-wire-format specification, so other clients can interoperate. For message-level chat encryption you do not need scripting at all, see the Encryption guide.

Worked examples

1 · A dice roller

Adds /roll (and /roll 20 for a d20).

alias roll {
  set -l %sides $1
  if ($len(%sides) == 0) { set -l %sides 6 }   ; default d6
  set -l %r $rand(1, %sides)                   ; 1 to %sides inclusive
  me rolls a %sides-sided die: %r
}

2 · Keyword highlighter

Locally flags lines that mention a watch-word, without touching the server.

on LOAD { set %kw_watch deploy }
on TEXT {
  if ($isme == false && $contains($lower($text), %kw_watch) == true) {
    echo $chan ⚠ watch-word from $nick
  }
}

3 · Auto-translate incoming lines

The pattern the bundled translate.hex uses: post each foreign line to a translation endpoint and echo the result underneath. Set your own endpoint and key at the top.

on LOAD {
  set %tr_lang $setting(applang)
  if ($len(%tr_lang) == 0) { set %tr_lang en }
  set %tr_ep https://libretranslate.example/translate   ; your endpoint
  set %tr_key                                            ; API key (blank = none)
}

on TEXT {
  if ($isme == false) {
    if ($len(%tr_key) > 0) { http.post %tr_ep q=$urlencode($text)&source=auto&target=%tr_lang&api_key=%tr_key tr $chan $text }
    else { http.post %tr_ep q=$urlencode($text)&source=auto&target=%tr_lang tr $chan $text }
  }
}

on SIGNAL:tr {
  if ($httpok == true) {
    set -l %out $json($httpbody, translatedText)
    if (%out != $2-) { echo $1 ↳ %out }   ; $1 = buffer, $2- = original text
  }
  else { echo $1 *** translate failed ($httpstatus) $httperror }
}

4 · Filter WHOIS replies

The pattern the bundled whoisfilter.hex uses: drop the numerics you never read. Editing one list is easier than remembering which code is which, so keep the comment next to it. The $whois test keeps the filter to WHOIS output, so a 301 away reply to a message you sent still shows.

on LOAD {
  set %wf_hide $list(310, 337, 339, 344, 350, 378, 379)
}

on NUMERIC {
  if ($whois != true) { return }
  if ($has(%wf_hide, $code) == true) { halt }
}

5 · Upload an image and paste the URL

The shape of the bundled imgpaste.hex. /img asks you for a file, uploads it, and sends the returned URL to the channel. It targets an endpoint that reads the file from an images field, strips photo metadata when strip_exif is set, and answers 200 with JSON either way, so the body decides success.

on LOAD {
  set %img_ep https://paste.example/img/index.php   ; exact URL, file name included
  set %img_base https://paste.example                ; the returned path hangs off this
}

alias img { media.pick -m image/* img_picked $chan }

on SIGNAL:img_picked {
  if ($mediaok != true) { return }
  toast Uploading $medianame
  media.upload -f images -p strip_exif=1 %img_ep $mediatoken img_done $1
}

on SIGNAL:img_done {
  if ($httpok != true) { echo $1 *** upload failed ($httpstatus) $httperror | return }
  set -l %err $json($httpbody, results.0.error)
  if ($len(%err) > 0) { echo $1 *** upload rejected: %err | return }
  set -l %path $json($httpbody, results.0.filePath)
  if ($len(%path) == 0) { echo $1 *** no path in the reply | return }
  msg $1 %img_base%path
}

6 · A scoreboard with a view

Tracks points per nick (/point nick) and shows a live board.

on LOAD { set %sb_score $map() }

alias point {
  if ($has(%sb_score, $1) == false) { setat %sb_score $1 0 }
  setat %sb_score $1 $calc($get(%sb_score, $1) + 1)
  board_render
}

alias board_render {
  view {
    surface bg #161b22 radius 16 pad 16 {
      column gap 8 {
        text Scoreboard bold textsize 18 color #ffffff
        foreach %p $sort($keys(%sb_score)) {
          row gap 8 { text %p weight 1 | text $get(%sb_score, %p) bold color #58a6ff }
        }
        button "Clear" clear fill
      }
    }
  }
}

on SIGNAL:clear { set %sb_score $map() | board_render }

Installing & editing

• Enable/disable, bundled scripts ship disabled; flip the toggle to opt in. A disabled script never runs and never registers its commands or launchers.
• Import/Paste, add your own .hex from a file or the clipboard.
• Edit, opens a full-screen editor with line numbers. Save & reload writes it back and reloads immediately, so changes (like an endpoint or API key) take effect at once.
• Revert, bundled scripts can be restored to their shipped default if an edit goes wrong.
• Remove, delete a script you added.

From here, browse the command reference for everything a script can drive, or the encryption guide for message-level E2EE that needs no scripting at all.