Version 20 (modified by nckmccnnll, 8 years ago) (diff)


Variant Maintainer's Guide

by Nick McConnell

Here is a (partially done) suggested categorisation for the Angband source files for the Core/UI split. The further to the right a file is, the more likely to be changed in a variant.

Library Front-end UI Needs adaptation Will have differences Will have large differences Likely Vanilla only
button Makefile* game-event cmd-context birth attack borg/
grafmode main* ui-event cmd-misc cave cmd-obj doc/
keymap cocoa/ ui-menu cmd0 death cmd1 stats/
parser gtk/ (!) ui-option game-cmd history cmd2 tests/
randname nds/ (!) ui option pathfind cmd3 wiz-stats
signals osx/ util prefs squelch cmd4
z-bitflag win/ xtra2 savefile calcs dungeon
z-file snd-sdl mon-msg score p-util effects
z-form target player files
z-msg ui-birth generate
z-quark ui-knowledge init2
z-queue ui-spell load
z-rand xtra3 save
z-term mon-timed spells1
z-textblock spell spells2
z-type timed store
z-util obj-ui tables
z-virt trap

This is 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). It refers to files in Angband 3.2.0.

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"; this should be the actual AngbandBase code.

Files you should not change Comments
button.c Mouse support
button.h "
debug.c Optional
debug.h "
game-event.c Critical - how the game handles events
game-event.h "
h-basic.h Really low level definitions and includes
macro.c Macro handling
macro.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 Windows makefile
parser.c General purpose file parser
parser.h "
randname.c Random name generation
signals.c Signal handling
snd-sdl.c SDL sound
textui.h Command handling
ui-event.h Mouse/keyboard input handling
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-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-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.
doc/doxygen.conf Optional documentation building. Change the variant name, plus anything else you feel like.
game-cmd.c Lower level list of commands, command handling. Changes corresponding to those in cmd0.c will be needed.
game-cmd.h "
gtk/ GTK port. Has some object- and event-related stuff in main-gtk.* which may need changing.
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. The same goes for Makefiles in subdirectories; I won't deal with them all individually.
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)
nds/ Nintendo DS port files. Really should all just work.
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 "
player/class.c Get class structure from ID.
player/player.c Player stat and level gain and loss. Can probably be unchanged.
player/race.c Get race structure from ID.
player/spell.c Casting of spells. Will need adjustment for different spell systems.
player/timed.c Unified handling of timed player effects. WIll need adjustment for what timed effects the variant has.
player/util.c Miscellaneous player routines. Need to be checked.
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, and possibly stat adjustments or even the inclusion of additional menus.
ui-birth.h "
ui-knowledge.c Knowledge screens. Data and/or menus will need to change, but the basic structure should stay.
ui-options.c Option screens. May need some adjustment to squelching, or addition or removal of some option menu entries.
ui-spell.c Spell book menus. Will need adjustment for different spell systems.
win/ Windows port files. Replace angband with variant name in the internals and (if you like) title of angband.rc.
xtra2.c Panel handling, direction/target input. May need changes for different level types (eg in variants with wilderness), or with different targetting needs.
xtra3.c Screen frame setup and event handling, and miscellaneous other display handling. Will need changes where the variant displays different things.

Finally, files which will need substantial change. I won't detail all the changes that are needed, but some of the big, cross-file changes that are likely to be needed are bitflag handling, random number handling, text printing to the screen and game command argument handling.

Files you should change Comments
attack.c Hitting, shooting and throwing code. Dependent on combat mechanics.
attack.h "
birth.c Birth process. Will need changes for different starting character features, quests.
birth.h "
cave.c High-level screen drawing. Will mainly need changes for different terrain.
cave.h "
cmd-misc.c Commands.
cmd-obj.c "
cmd1.c "
cmd2.c "
cmd3.c "
cmds.h Command function definitions
death.c Printing tombstone, post mortem. Will need change for any variant-specific stuff that happens here (eg bones files)
defines.h Big list of constants etc. Will vary.
dungeon.c Main game loop. Will need changes for anything that happens every turn (eg regeneration)
effects.c All item and spell effects. Structure should be similar, effects will vary.
effects.h "
externs.h Function prototypes and globals. Will vary.
files.c Character dumps and help.
files.h "
generate.c Dungeon generation. Will probably have many differences.
generate.h "
init2.c Reading of edit files, using the parser. Change as required.
init.h "
list*.h New, awesome way of reading in game data. Number of files and nature of data will be variant-specific.
load-old.c Old savefile loading.
load.c Current savefile loading. Dependencies for make. Generate using depgen.
Makefile.src Specific source files for make. Make sure this list is up to date, and your variant, version and copyright details are set.
monster/constants.h Monster attack macros.
monster/melee1.c Monster attacks.
monster/melee2.c Monster spellcasting and movement.
monster/monster.h Monster function prototypes.
monster/monster1.c Monster descriptions.
monster/monster2.c Monster management.
object/constants.h Empty
object/identify.c ID by use.
object/inventory.h Almost empty
object/obj-desc.c Object names. Structure is worth using.
object/obj-info.c Object descriptions. Structure is worth using.
object/obj-make.c Object generation.
object/obj-power.c Object power calculation. Used for pricing and randarts.
object/obj-ui.c Item selection and display.
object/obj-util.c Object utility functions.
object/object.h Object function prototypes and constants.
object/randart.c Random artifact generation.
object/tvalsval.h List of tvals and svals.
save.c Low level savefile writing.
spells.h Spell function prototypes.
spells1.c Spell effects.
spells2.c Spell functions.
squelch.c Squelching. Depends on ego types, at least.
squelch.h "
store.c Stores.
store.h "
tables.c Data arrays.
trap.c Handling of traps.
trap.h "
types.h typedefs and structs. There are also types.h files in player/, monster/ and object/ - personal choice as to how this is handled.
variable.c Global variables.
wiz-spoil.c Spoiler generation.
wiz-stats.c Collection of generation stats.
wizard.c Wizard mode commands.
wizard.h "
x-spell.c Player spell definitions.

Current AngbandBase source files

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


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.