Clan Lord's Macro

Clan Lord’s macro language is the client-side scripting system built into Clan Lord, the persistent-world online RPG released by Delta Tao Software in 1998 and often described as the Macintosh’s first MMORPG. It began life as a plain text file of typing shortcuts and grew, over a few years of incremental client updates, into a small but genuinely programmable language with global and local variables, string and arithmetic operators, conditionals, subroutine calls, randomised alternatives, and label/goto loops. Nearly three decades after its introduction it is still shipped, still documented on Delta Tao’s website, and — judging by the activity of the community macro library — still in everyday use by the game’s players.

It is a language almost nobody has heard of and a surprising number of people have written, because in Clan Lord the macro file is not an optional power-user feature — it is how a healer heals efficiently, how a bard plays a song, and how a character greets a friend without typing thirty characters.

History & Origins

The game came first

Clan Lord launched on 18 October 1998 for the Macintosh. Delta Tao Software — better known to older Mac users for Spaceward Ho! and Color Dark Castle — built it as a cooperative, largely non-PvP world where players communicate through speech bubbles and a “sunstone” messaging system, and where nearly every interaction is issued as a typed slash command: /action, /pose, /give, /thinkto.

That design is the whole reason the macro language exists. A game whose interface is a text box invites automation of the text box.

February 1999: the first macros

Although the language is commonly dated to the game’s 1998 launch, Delta Tao’s own “What’s New” changelog tells a slightly later story. The 1998 archive contains no mention of macros at all. The first entry is dated 17 February 1999:

Added macro keys and short hand expansions. See the text file clmacros for details and examples.

That is the language’s real beginning: key-triggered macros and abbreviation expansion, documented in a plain text file called clmacros that shipped alongside the client. On 25 March 1999 multi-line macros followed, together with the \s and \P escapes — the point at which a macro stopped being one substitution and became a sequence of commands.

Because the game itself dates from 1998, the macro language is frequently attributed to that year; the more precise reading of the official record is that Clan Lord shipped in October 1998 and its macro language appeared roughly four months later, in February 1999.

The one breaking change

On 6 October 1999 Delta Tao posted a terse warning:

Macros have changed. Most likely you will need to update your macro files. Sorry for the inconvenience.

The same entry notes that “the entire script engine has been rewritten.” This appears to be the language’s only documented compatibility break, and it is why older community references distinguish between the previous macro language and the current one. No comparable warning appears in the changelog afterwards.

Everything after 1999 has been additive. Client v147 (September 2000) brought string concatenation and full equipment-slot access; v155 (November 2000) added the @login startup hook; v256 (October 2002) added C-style block comments; v533 (February 2008) added the experimental share-list variables. The core shape of the language has not changed since.

Design Philosophy

The language is built around one unusual premise: a program is a thing that types for you. A macro does not call an API. It emits characters into the game’s input box exactly as if the player had typed them, and when it emits a carriage return, the accumulated text is sent to the server.

Three consequences follow.

Everything is text. There is no distinction between “printing” and “executing” — a bare line of a macro is output. Commands (pause, set, if, call) are recognised by their first word; anything else is text or a variable reference to be concatenated.

The trigger is part of the declaration. A macro is a trigger plus a body. There is no main program, no event-registration call — the syntactic form of the trigger determines whether it fires on typed text, on abbreviation expansion, on a keystroke, on a mouse click, or on an explicit call.

The player is meant to stay in the loop. Because macros act as the player’s keyboard, Delta Tao and the community have long drawn a line between macros that save typing and macros that play the game unattended. Community documentation notes that players running automatic hunting and healing macros — ones that benefit a character with no intervention from the person at the keyboard — have been punished for it. The language is deliberately weak in ways that reinforce this: it cannot read the game world’s state beyond a handful of variables about your character, your selection, and what you just clicked.

Key Features

Macro files and includes

The client loads the file in the Macros folder whose name matches the character’s name — a character called Gaia gets a file called Gaia. If it does not exist, the client creates a blank one, plus a Default file. Files pull in others textually:

1
2

include "Default"
include "Item Macros"

The manual describes this literally: the statement “loads the contents of the other file exactly as if it were inserted where the include is.” There is no module system and no namespacing — it is a textual paste, which is precisely what a macro language of this era would do.

Four kinds of trigger

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Expression macro — fires when you type "lol" and press Return
"lol" "/action laughs until he cries.\r"

// Replacement macro — expands the abbreviation as you type
'OC' "Orga Camp"

// Key macro — modifiers chained with hyphens
command-m "/give " @selplayer.simple_name " 1\r"

// Function macro — invoked only by "call"
subroutine
{
  who " is a " prof ".\r"
}

Key names cover f1–f16, escape, tab, return, space, home, end, pageup, pagedown, the arrow keys, enter, clear, help, undo, del and click; modifiers are command, control, option, shift and numpad. Mouse buttons appear as click2, click3 and so on (right-click is a synonym for click2), and scroll wheels as wheelup, wheeldown, wheelleft and wheelright.

The option key gets a documented wrinkle that only a Mac language would have: because typing option-s on a US keyboard actually produces ß, the macro must be declared as option-ß, not option-s.

A function macro named @login runs automatically on joining the game or reloading macros — the language’s one lifecycle hook.

The long and short forms

One command can be written inline; more than one requires braces, one command per line:

1
2
3
4
5
6

"/sleep"
{
  "/pose lie\r" "/action lies down and closes his eyes.\r"
  pause 10
  "/sleep\r"
}

Attributes

Attributes begin with $ and modify how the client treats a macro rather than executing at any particular point in it:

Variables

Variables are declared with set. A set outside any macro creates a global; inside braces it creates a local that shadows any same-named global. setglobal reaches out from inside a macro to modify the global.

1
2
3
4
5
6

set who "Kerial"

"set1"
{
  setglobal who "Ternia"
}

Undefined variables are not an error — they expand to nothing, which is very much in keeping with a text-substitution language.

The client exposes a fixed set of read-only @ variables: @my.name and @my.simple_name; the fifteen equipment slots (@my.right_item, @my.left_item, @my.head_item, @my.coat_item and so on) plus @my.selected_item; @selplayer.name and @selplayer.simple_name for the selected character; @click.name, @click.simple_name, @click.button and @click.chord inside click macros; @text for the typing box contents at the moment the macro fired; @textsel for the selected portion of it; and @random, a fresh number between 0 and 9999 on every reference.

A parallel @env family is writable and controls execution: @env.echo, @env.debug, @env.key_interrupts and @env.click_interrupts.

Any variable can be sliced by word or letter, both zero-indexed:

1
2
3
4

@text.word[0]      // first word
@text.num_words
@text.letter[2]
@text.num_letters

This is the closest the language comes to a data structure, and the community used it as one — the 2008 @my.shares_in variable returns a space-separated list of names, iterated with .word[n] against .num_words.

Operators and coercion

set accepts + - * / %. The + operator is overloaded on the text/number boundary in an asymmetric way that reveals the implementation:

Comparison operators are >, <, <=, >=, == and !=. When both sides are strings, < and > do not compare alphabetically — the manual states they are “interpreted as ‘is a substring of’”, which makes if "peace" < @text a perfectly idiomatic way to ask “did the player mention peace?”

Control flow

if / else if / else / end if behave conventionally. Loops are built from label and goto, with if as the only brake:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

f12
{
  set num 0
  label mark
  set num + 1
  if num < 10
    pause 5
    "Counting: " num "\r"
    goto mark
  end if
}

random picks one alternative from a list, optionally with no-repeat to forbid the same choice twice running — a small feature that exists because this is a roleplaying game and repeated identical greetings break the illusion:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

"greet"
{
  random no-repeat
    "Greetings "
  or
    "H'loi "
  or
    "Good day "
  end random
  @selplayer.name "\r"
}

call invokes a function macro and returns; the manual notes that local variables of the calling macro are visible to the called one, which makes call a dynamically scoped subroutine rather than a lexically isolated function. There are no parameters and no return values — you set the locals the callee expects, then call it.

pause suspends a macro for a number of frames, where the manual gives a frame as approximately one quarter of a second, and explicitly notes that the rate varies: a little slower during peak hours, a little faster off-peak. Timing in this language is a negotiation with a live server, not a guarantee.

message writes to the player’s own sidebar only. It never reaches the server, so it never appears in other players’ clients or in recorded movies — which makes it the language’s printf for debugging.

Escapes, comments and the panic button

Escapes use a backslash: \\, \", \', \r. Note the asymmetry with the game itself — typed directly into Clan Lord, a command may begin with / or \, but inside a macro expression it must be /action, never \action, because the backslash is already the escape character.

Comments are // to end of line and /* ... */ across lines, the latter added in client v256 in October 2002.

And because goto with no loop guard is exactly as dangerous as it sounds in a language that types on your behalf, the client reserves control-escape to stop all running macros. The text box draws a thicker outline whenever a macro is executing, so a runaway script is visible before it is embarrassing.

Evolution

The arc is unusually easy to trace, because Delta Tao has kept a public changelog since 1998 and versions every client build.

The 2008 entry is a good miniature of how the language evolves: a feature appears in the Mac client marked explicitly preliminary — “Use it at your own risk — but if you do find any problems, please report them! Once we get the bugs ironed out, if it turns out to be widely useful, it’ll be added to the Windows client as well” — and graduates to the other platform only after players exercise it.

Since then the changelog’s macro mentions essentially stop. The language reached the shape its users needed and Delta Tao left it there.

Current Relevance

Clan Lord is still running. Delta Tao ships a “Chaos Storm” update on a roughly monthly cadence; the changelog records v1497 on 5 August 2026, continuing a sequence that runs unbroken back through the 1990s. Delta Tao made the game free to play on 21 January 2009 — monthly fees became optional and expired accounts were reinstated — and it has carried a small, steady community since.

Delta Tao’s download page currently offers a complete client for macOS 10.6–10.14 and a complete client for Windows, and points players on macOS 10.15 and later to a third-party client. Because the macro system is a feature of the client rather than the server, the language travels with whichever client a player runs.

The documentation remains where it has always been: a macro manual, a basics primer, a listing of the default macro file, and links to player-written collections by Healery and Noivad — all on deltatao.com, all in the same plain style. (That index also lists several unofficial macro archives that Delta Tao notes are now offline.) The community side is centred on CLUMP, the Clan Lord Unofficial Manual Project, whose wiki carries a large profession-organised macro library.

Why It Matters

Clan Lord’s macro language will never appear in a compilers course, and no one has written a paper about it. Its interest is historical and sociological.

It is a fossil of a specific idea about MMO automation. In 1999 the question of how much a client should be allowed to do on a player’s behalf was genuinely unsettled. Clan Lord’s answer — give players real control flow, but give them almost no visibility into game state, and enforce the rest socially — is a distinct and coherent position, and one you can still read directly in the language’s feature set. The variables it doesn’t have are as deliberate as the ones it does.

It shows a text-substitution system evolving into a language in public. Most languages arrive with a design document. This one grew one changelog entry at a time: abbreviations in February 1999, multi-line bodies in March, variables and concatenation by 2000, a startup hook that November, block comments in 2002. Delta Tao’s archive is an unusually complete record of a domain-specific language accreting features under pressure from its users, with exactly one moment where backward compatibility had to be broken.

It is proof that small languages have very long lives. A scripting language introduced for a Macintosh game in early 1999 is still loading macro files written by players in 2026, on an operating system that did not exist when it was designed, in a game that has been patched roughly every four weeks for over a quarter of a century. Whatever else it is, it is durable.

Further Reading

• Clan Lord Macro Manual — the complete official reference
• Clan Lord Macro Basics — introductory primer
• Default Macros — the annotated shipped macro file
• Clan Lord What’s New archive — the versioned changelog cited throughout this page
• CLUMP: Clan Lord Unofficial Manual Project — community macro library