Variant Maintainer's Guide

by Nick McConnell?

This is going to be a description of AngbandBase (the low level Angband code that should be common across variants) and a guide to variant maintainers on how to use it (and adapt other Angband code to suit them).

Guide to angband/src

This is a rough (unfinished) division of the Angband source files into categories for anyone planning to base their variant on current Vanilla. I will illustrate with examples from my experience with doing this in FAangband where I think it will help.

The first category is "files which no variant maintainer should change"

Files you should not change	Comments
buildid.c	Optional for identifying individual builds
button.c	Mouse support
button.h	"
debug.c	Optional
debug.h	"
game-event.c	Critical - how the game handles events
game-event.h	"
guid.c	?
guid.h	"
h-basic.h	Really low level definitions and includes
keymap.c	Keymap handling
keymap.h	"
main-crb.c	Mac port
main-gcu.c	Curses port
main-nds.c	Nintendo DS port
main-sdl.c	SDL port
main-win.c	Windows port
main-x11.c	X11 port
main-xxx.c	platform port template
main.c	Linux/Unix? main file
main.h	"
Makefile.nds	Nintendo DS makefile
Makefile.win	Windows makefile
parser.c	General purpose file parser
parser.h	"
randname.c	Random name generation
randname.h	"
signals.c	Signal handling
snd-sdl.c	SDL sound
textui.h	Command handling
ui-event.c	Mouse/keyboard input handling
ui-event.h	"
ui-menu.c	Menu handling
ui-menu.h	"
ui.c	Some display routines
ui.h	"
x-char.c	Accented characters
x-char.h	"
z-bitflag.c	Bitfield handling
z-bitflag.h	"
z-debug.h	?
z-file.c	File handling
z-file.h	"
z-form.c	Text formatting
z-form.h	"
z-msg.c	Game messages
z-msg.h	"
z-quark.c	Inscriptions
z-quark.h	"
z-queue.c	Queue (mainly for events?)
z-queue.h	"
z-rand.c	Random numbers
z-rand.h	"
z-term.c	Displaying in a window
z-term.h	"
z-textblock.c	Displaying and printing chunks of text
z-textblock.h
z-type.c	Datatypes
z-type.h	"
z-util.c	String and other miscellaneous routines
z-util.h	"
z-virt.c	Memory handling
z-virt.h	"

The next category consists of files which currently only need minimal changes (typically changing "angband" to "variant name", or similar), and which could potentially be altered in the Angband source so that no changes are required.

Files needing minimal changes (1)	Comments
angband.h	Maybe change included files - can be used unaltered if you use the same player, monster, object subdirectories as Angband
buildid.h	Optional for identifying individual builds - change Angband to variant name
cmd-misc.c	Maybe change included files
config.h	Probably fine as is
util.c	Probably no need to change - some variants might have other routines of this type

The next category again only needs small (or no) changes, but where changing the Angband source isn't really an option.

Files needing minimal changes (2)	Comments
cmd0.c	High level list of all commands, command menu handling. Variants will need to adapt the list.
cmd4.c	Character dumps, screen redraws, message recall, etc. I needed to change this because of a different 'C' screen; other variants may not.
game-cmd.c	Lower level list of commands, command handling. Changes corresponding to those in cmd0.c will be needed.
game-cmd.h	"
history.c	Player history. Variants can add different types of event to record in the history.
history.h	"
Makefile	Main makefile for unix/linux. Change variant name, maybe subdirectories
Makefile.nmake	Makefile for MSVC (operational?). Change variant name.
Makefile.osx	Builds OSX app. Change variant name, check other files to be installed (in top level directory and lib)
Makefile.std	No-configure makefile (usually used as a quick attempt or fallback for linux or unsupported systems). Change variant name, check other files to be installed (in top level directory and lib)
options.c	List and handling of options. Change list as needed.
options.h	"
osx/	OSX-specific files; change Angband to variant name where it occurs.
pathfind.c	Pathfinding (from mouse movement) and running. Variants with different terrain will need to make changes.
pathfind.h	"
prefs.c	Pref file handling. Likely to be unchanged; changes needed if your variant supports saving different stuff in pref files.
prefs.h	"
savefile.c	High level savefile handling. Includes a list of blocks to save and load, which may vary; handling of old savefiles may also need alteration.
savefile.h	"
score.c	Scores file handling. Actual score details may need to change.
target.c	Targetting. May need tweaking for terrain, monster or object differences.
target.h	"
ui-birth.c	Birth process menus. Will need some race/class-specific changes.
ui-birth.h	"

Current AngbandBase source files

Note that current AngbandBase uses 3.2.0 - some names in more recent Angband will have changed

Makefile.*

z-*

x-char.*

ui.*

ui-*

main*

game-event.*

button.*

macro.*

prefs.*

signals.c

snd-sdl.c

textui.h

Some of these are clearly wrong - for example, ui-knowledge and ui-spells shouldn't be in here and parser.* should. The guide to angband/src above should be more useful for pretty much every purpose, when it's finished.

Putting all these into a library seems like a good idea.