Unangband Edit Files - Part Two (Customising)

(You'll probably want to start with part one of this series)

The edit files in Angband are a gateway drug: they exist to allow players to modify the game without requiring an understanding of coding or compilation. This is the reason there are so many variants of Angband – it is very easy for a player to modify one or more entries in an edit file to customise the game to their liking, and then progressively change the game so that it becomes a full variant. Outside the Angband community, these would be called mods or total conversions.

An understanding of the ability to read code is highly recommended if you wish to customise the existing edit files. This is for several reasons:
• The edit files themselves are incompletely documented. This file is an attempt to rectify part of that issue.
• Unangband is a work-in-progress and constantly evolving. This means that the SVN repository is the best place to get a view of the developer intentions, and the released source code for the version you are playing the best reference for specific implementation of the edit files.
• Documentation can at only at best discuss the code at a high level. For an exact understanding of how the edit files interact and features of these files, the source code and generated executables are your primary reference.

Luckily the Angband code base is well documented, a tradition that Unangband attempts to continue, although has done so in fits and starts. A later article in this series will provide a guide to reading the source code in conjunction with the edit files.

Customising the edit files is ‘simply’ a matter of making a change to the .txt file, saving it and restarting Angband. This will automatically update the corresponding .raw file as a part of the game start up. Various checks are made to ensure that the changes parse correctly, but not a lot of data bounds checking is enabled, so it is relatively easy to crash the Unangband executable, by putting invalid entries in the edit files.

If you wish to add entries to the end of a particular edit file, you’ll need to edit limits.txt. This file covers the initialisation of a number of maximum entries in each of the other edit files, as well as upper bounds for dynamically allocated memory for holding the text and descriptions for the majority of these files, and a few other values (e.g. the maximum numbers of monsters and objects on a dungeon level).

You should familiarise yourself with the game-play first, and then reading the edit files, before you make any changes. This will give you a good feeling for how changing the edit files makes corresponding changes in game. A common first attempt may be to make easy monsters have powerful or valuable drops, by adding various DROP_ flags to the monster type. Equally, monster vital statistics can be changed, allowing you to achieve impressive speed runs.

You’ll quickly learn (unless you are of a certain frame of mind), that changing the edit files to win the game quickly ruins the experience for you, and you should refrain from trying this, or even peeking at the information contained inside, to discover the surprises ahead. Unfortunately, this temptation is often too great – and a challenge that few open source games are likely to be able to overcome. But with the rise of sites like gamefaqs.com and programs like Glider, the same information sharing challenge is faced by commercial games as well. Luckily, the procedural generation, randomness and other roguelike features such as perma death ensure that Unangband remains a challenge, even with complete knowledge of the game rules.

The edit files are not as expressive as a full scripting language and you’ll find that there are a number of cases where various values in the edit file have hard-coded dependencies in the game code, or interact in unexpected ways. Unangband has tried to reduce the number of instances where this happens in the ‘core’ Angband edit files, but at the same time feature creep has meant that overall it is probably just as bad, if not worse than Angband itself. This series of articles attempts to address this.

(Stay tuned for part three).