Articles & Documents

MAngband Hacking

This document describes some technical notes/aspects of MAngband/Angband that I learned while writing an SDL2 interface (so I could play MAngband "unencumbered" on various platforms).

z-terms

MAngband, being a derivative of Angband, uses the concept of "virtual terminals" or "z-term"s. A z-term is a matrix of rows*columns of cells that correspond to a basic terminal device. Each cell in a z-term may have an "attribute", such as a color, as well as a "character". Characters may be drawn at arbitrary locations within the matrix and the z-term does various intelligent checks to ensure that the minimal amount of updates are triggered to signify an update to whatever the front-end may be.

Getting into the topic of front-ends, z-terms provide a set of a function pointers that act as hooks and are expected to handle certain types of data/information. These hooks are intended to be used to create, draw, and destroy a "z-term" and its interface. These hooks are:

void (*init_hook)(term *t);
- Function that should create the "z-term" interface
void (*nuke_hook)(term *t);
- Function that should destroy the "z-term" interface
errr (*user_hook)(int n);
- User-defined hook, not sure
errr (*xtra_hook)(int n, int v);
- Extremely important function that handles "xtra" events, such as polling for events, playing a sound, delaying, etc.
errr (*curs_hook)(int x, int y);
- Function for drawing the cursor at the given location
errr (*wipe_hook)(int x, int y, int n);
- Function for wiping "n" characters from the given location
errr (*pict_hook)(int x, byte a, char c);
- Function for drawing a special "pict" character -- a graphic image. Byte attribute "a" and char "c" correspond to the row and column of the desired sprite. This function is called when attr "a" and char "c" have their high bits set, thus signifying an image. Proper "row" and "column" coordinates must be acquired by toggling the high bit, e.g., "attr &= ~(1 << 7);" and "ch &= ~(1 << 7);".
errr (*text_hook)(int x, int y, int n, byte a, cptr s);
- Function for drawing a string with attributes from the given location

In the case of MAngband, there are console(cap,ibm,gcu), SDL, X11, Xaw, and Windows "z-term" implementations. Each one of these implementations handles the interfacing of at least 1 "z-term" to the user interface of the implementation.

The base-line requirements for a "z-term" interface is to:

1. For each z-term, create a visual window
2. Add in a hook to write characters and clear cells
3. Handle events and sent to the appropriate z-term
4. Handle closing/freeing the window

MAngband z-term usage

MAngband can use a total of 8 z-terms, the first of which is the only required one. These terms and their function descriptions are:

0 / Main "screen" window
1 / ???
2 / ???
3 / ???
4 / Chat
5 / ???
6 / ???
7 / ???

Basic MAngband logic

The main "connected" loop for MAngband is:

keymap_init();
show_motd();
Net_start()
Input_loop();
- 1. Sleep, then read socket
- 2. Send commands
- 3. Read commands via process_command(), then request_command()
- 4. flush input via Term_fresh()
- 5. window_stuff() ???
- 6. Keep alive
Net_cleanup();
quit(NULL);

MAngband commands and keymaps

One of the more difficult aspects of interfacing with the "z-term" is understanding the proper way to pass keyboard input.

kettek

Games