Table of Contents

Client Scripting Interface

The client scripting interface can be used to control a Crossfire client using an external program (script). This interface can be used to extend the client or automate repetitive tasks (see sample scripts).

The script communicates with the client by reading information from standard input and writing commands to standard output. Scripts can be written in any programming language. The same client scripting interface is used by the GTKv2 client and the JXClient. Any discrepancy should be reported as a bug.

Using Scripts in the Client

Several client commands are available to start, stop, list, and communicate with scripts:

Writing Scripts

The script must be executable (e.g. chmod +x with an appropriate shebang). For some languages, it may be necessary to write a wrapper script to start the program. Additionally, on Windows systems where the shebang is not supported, the player must provide a means of running such a script. For example script python <path-to-script> if you are using python.

Hello World

Save the following script in a file, mark it executable, and run it in the client using the script command: 

  #!/usr/bin/env python
  print("issue 1 1 say Hello, world!")

The issue interface command runs a given command as if a user typed it into the command window. It takes 3 arguments: repeat, the number of times to repeat the command (typically used for dropping items); must_send, an integer either zero or one; and command, the command to execute.

Monitoring

What to do next? As you can see, our script doesn't wait very long after issuing commands. And it doesn't get information from the client at all. In fact it just hopes it is really speaking to the client. We are going to write a simple script which will issue a command to the client and then gets the result. We are going to spy!

Use the following script and run it in client. Ensure you ran the client in a console or you won't see any result! 

#include <stdbool.h>
#include <stdio.h>

#define LENGTH 200

int main() {
    char buffer[LENGTH];

    // Ask the client for a copy of all commands sent to the server.
    fprintf(stdout, "monitor\n");
    fflush(stdout);

    // Read the commands and print to standard error.
    while (fgets(buffer, LENGTH, stdin) != NULL) {
        fputs(buffer, stderr);
    }

    return 0;
}

Now move a bit in the game. A few steps are enough! Look at your console, you should see something like this: 

monitor 0 0 east

monitor 0 0 east

monitor 0 0 east

monitor -1 0 run 7

monitor -1 1 run_stop

If you type the command scripts in your client you will see our script is still running.

Let's look more closely at the code. We define a character buffer and a length. We will use the buffer to read what the client sends to the script. Then our script sends to the client the command monitor (don't forget the \n). This command asks the client to give the script a copy of all commands sent from the client to the server. Now each time a command is sent from client to server, the script will get a “monitor <command>” string.

A strange C command

fflush(stdout)

The stdout has something called a buffer. When you write to output device, it's not immediately sent to it. For performance reasons, successive print to stdout are grouped. Most of the time, \n is enough to force sending of data, but we ensure all data are sent to client by flushing the stdout (force empty buffer). In the future, when you think client didn't get a command but the script did send it, ensure you flushed stdout.

Then comes a loop. This loop will read from stdin (where client puts information for the script) and copy them to stderr (our only access to console since stdout is a connection to client). Because I don't want to use scanf I used the binary read and write commands. Stdin is the file handle 0 and stderr is file handle 2. We first read up to 200 char from stdin and if we read something we write it to stderr. If we didn't read anything, that means we have lost the client (shouldn't happen) and we simply exit.

Since we asked to monitor all commands from client to server, we get them. These commands are our move commands and they use the same format as issue. If you run our first script while this second script is still running, you will still say hello world, but you'll get the following in your console: 

monitor 1 1 say hello world

So client sends us lines made of 

monitor <repeat> <must_send> <command>

Now kill the script by typing command 

scriptkill <pathtoscript>

(The JXClient additionally recognizes partial script names as well as numbers and has an additional command scriptkillall to stop all currently running scripts in one go.)

or 

scriptkill <number>

Then type scripts to ensure it's stopped (or to figure out the number of the script). Edit it, comment the line printf(“monitor\n”), compile and run the script again. Move and look at console. You see nothing. The script didn't ask anything so the client didn't tell it anything. Your script will only get that for which it asks.

Now try the following code: 

#include <stdio.h>

int main (){
      char buf[200];
      int len;
      printf ("watch stats\n");
      fflush (stdout);
      for(;;){               
              len=read(0,buf,200);
              if(len)
                      write(2,buf,len);               
              else
                      exit(-1);
      }
}

This time we are requesting commands sent from server to client. But there are far more of them. So watch takes as argument the beginning of all commands we want to get. Here we want every stat command from client. And in our console we see, when running script: 

watch stats food 398

watch stats food 397

watch stats food 396

watch stats food 395

Wow! This mean we know when food is low and we can ask our script to invoke restoration (remember the issue command?) when our character's food gets below 50! No starvation anymore.

Reference

There are two things you can still do with scripts. The first is to request a bit of information. The client then tells the script what it wants to know. The second thing is triggering an action of the script from client interface. The command scripttell allows player to say something to a script. The script will get the exact command typed by player. See below for command list.

Commands to client

Here is a list of command the script can send to client.

<box round | Data Type Table>

Data Type Comment
range Return the type and name of the currently selected range attack
stat <type> Return the specified stats
stat stats Return Str,Con,Dex,Int,Wis,Pow,Cha
stat cmbt Return wc,ac,dam,speed,weapon_sp
stat hp Return hp,maxhp,sp,maxsp,grace,maxgrace,food
stat xp Return level,xp,skill-1 level,skill-1 xp,…
stat resists Return resistances
weight Return maxweight, weight
flags Return flags (fire, run)
items inv Return a list of items in the inventory, one per line
items actv Return a list of inventory items that are active, one per line
items on Return a list of items under the player, one per line
items cont Return a list of items in the open container, one per line
map pos Return the players x,y within the current map
map near Return the 3×3 grid of the map centered on the player
map all Return all the known map information
map <x> <y> Return the information about square x,y in the current map (relative to player position)
player Return the player's tag and title
skills Return a list of all skill names, one per line (see also stat xp)
spells Return a list of known spells, one per line
stat paths Return spell paths: attuned, repelled, denied

Note: player, skills, spells, stat path were added between versions 1.11 and 1.50 of the GTK2 client.

Information from client

Here is an incomplete list of information strings send by client to script. Those informations are sent only because the client asked them, except for scripttell.

The issue command

This command has it's peculiarities.

Usage: 

issue [<repeat> [<must_send>]] <command>

The next examples should clarify the use of numeric parameters.

Some examples that work: 

issue 0 0 apply
issue 0 1 apply
issue 1 0 apply
issue 1 1 apply
issue 1 1 stay f
issue 0 0 stay f
issue 1 1 south
issue 0 0 south
issue 0 0 examine bag
issue 1 0 get nugget (works as 'get 1 nugget')
issue 2 0 get nugget (works as 'get 2 nugget')
issue 1 1 get nugget (works as 'get 1 nugget')
issue 2 1 get nugget (works as 'get 2 nugget')
issue 0 0 get nugget (works as 'get nugget')
issue lookat 2 3 (works as left clicking on the spot 2 tiles to your right and 3 tiles down, coords are relative to player position)

Some examples that do NOT work: 

issue apply
issue 0 apply
issue 1 apply
issue 2 0 apply  (works only once, not twice as expected)
issue 2 1 apply  (works only once, not twice as expected)
issue get 4 nugget
issue 4 1 south  (works only once, not 4 times as expected)
issue 4 0 south  (works only once, not 4 times as expected)
issue 1 1 lookat 2 3
issue 0 1 lookat 2 3
issue 0 0 lookat 2 3

Platform-Specific Notes

Known issues are:

A Few Thanks

Scripting was rendered initially functional with a patch from archaios and is being kept current by GTKv2 client maintainers Partmedia and crowbert, and JXClient maintainer Ragnor.