=================
Modifying Angband
================= 

Angband is not just a great game in its own right, it is really easy to modify.
Much of the detail of the game is contained in text data files.  These can be
changed using nothing more than a text editor for an immediate change to how
the game works.

These data files are in lib/gamedata.

Each file has a header which describes the lines which make up entries of the
file, and for the most part this will make it clear what needs to be done to
make changes to the files.  Below is brief description of each of the files.

Those who want to change the game more than is allowed just by varying the
data files will need the source code.  Below the data file descriptions is a
brief discussion of where to start on such an endeavour. 


The data files
==============

constants.txt
  This file contains game values such as carried item capacity, visual range
  and dungeon level and town dimensions.  

object_base.txt
  This file contains the names and common properties of the basic object
  classes - scroll, sword, ring, and so on.  All objects have an object base.
  Each object base is assigned a 'tval' - a numeric index.  The tvals are
  defined in src/list-tvals.h.  While adding new object bases is possible,
  it is unlikely to do much without deeper changes to the game.


object.txt
  This file contains the names, properties and description of all the object
  types that appear in Angband.  New object kinds can easily be added to this
  file, or existing ones edited.  Each object defined by this file has an
  object base, and is also allocated another numeric index called an 'sval'.
  A tval-sval pair completely identifies an object - since the tval and sval
  are saved to savefiles, removing or adding objects is likely to render
  existing save files unusable.

ego_item.txt
  This file contains the names, properties and description of ego items, which
  are magically enhanced weapons and armour.  New ego items can be added or
  removed at will, although removing or changing one with an instance currently
  in the game might cause problems.

artifact.txt
  This file contains the names, properties and description of artifacts, which
  are unique items - only one of each will ever be generated.  If you are
  considering major changes, new artifacts are one of the most visible signs of
  a change of theme.  Regardless, new artifacts are easy and fun to design.

names.txt
  This file contains lists of words which are used to generate names for
  random character names, random artifacts and scrolls.  Again, in the case
  of a change of theme, this is a good way of displaying the new theme.

activation.txt
  Activations are used for artifacts and some regular objects, and could be
  used for ego items (although none currently are).  Some standard artifacts
  from artifact.txt have activations, and random artifacts may have any
  activation from this file chosen for them.  Activations can be made up of
  any effects (see effects.c and list-effects.h).

flavor.txt
  Items such as potions and wands are assigned a flavor per object kind,
  different in each game.  There need to be at least as many flavors for each
  flavored object base as objects with that base.

monster_base.txt
  Monster bases are the monster equivalent of object bases - classes of monster
  like orc, troll or vampire.  This file contains the properties common across
  all monsters in each of these classes.

monster.txt
  This contains the detail of all monster races, each of which will have its
  monster base properties plus additional ones.  Some monsters are unique, and
  once killed will never reappear.

monster_spell.txt
  All the spells that can be cast by monsters (and are referred to in the
  'spells:' lines in monster.txt) are defined in this file.  As with
  activations, monster spells are built up from effects.

pain.txt
  This file contains the various messages that are given to describe how a
  monster responds to attack.

pit.txt
  Dungeon levels can contain pits - rooms full of a particular selection of
  monsters.  This file defines these selections.  They can also be used, for
  example, to generate partial or complete dungeon levels with themed monsters.

class.txt
  This file completely defines how player classes work, including all details
  of castable spells.  There are some class-specific properties hard-coded,
  which are referred to via the 'flags:' lines, and appear in
  list-player-flags.h.

p_race.txt
  This file defines all player race characteristics.  Race-specific code is
  handled as for classes.

body.txt
  Every player race has a body, which defines what equipment they can use.
  Currently there is only one body, which all races use, but this is easily
  changeable for significant effect.

history.txt
  This file is for creating the player background found on the character
  screen.  If a new race is introduced, a selection of background information
  for it will need to be added.

hints.txt
  This is simply a list of general pieces of advice that shopkeepers will give
  to their customers.

quest.txt
  This file defines the quest monsters (Sauron and Morgoth) and where they
  appear.  This currently can't easily be changed, as there are still
  hard-coded aspects of the quests.

terrain.txt
  This file defines the kind of terrain which can appear in Angband, and its
  properties.  Current terrain can be changed (with possibly large effects),
  but removing it without code changes is likely to break the game.  Adding
  new terrain will have no effect by itself, because there is no mechanism
  for it to appear.

trap.txt
  This defines all traps, door locks and runes.  Actual trap effects appear in
  effects.c and list-effects.h.

room_template.txt
  This is a list of templates for interesting-shaped rooms which appear in the
  dungeon.  These can easily be changed and new ones added.

vault.txt
  Similar to room_template.txt, this handles vaults, which are very dangerous
  and lucrative rooms.

dungeon_profile.txt
  This file contains fairly technical details about the different types of
  dungeon level which can be generated.  The actual generation routines are in
  gen-cave.c; the information here consists of parameters for generating
  individual levels, and for how often given level types appear.

store.txt
  This details the shop owners and their relative generosity.

blow_effects.txt
  This defines effects to the player caused by monster attacks.  The simplest
  monster attacks just deal damage, but others can affect the player's status,
  stats or inventory.

blow_methods.txt
  This details the different ways monsters can attack (hit, claw, etc.).  It
  affects the messages the player gets, and also whether the blow can stun
  or cut the player.

brand.txt
  This details how weapon brands work.

slay.txt
  This details how weapons can be more effective against certain monsters.

curse.txt
  This file contains all the different curses that can be applied to objects.
  It includes what type of object they can be applied to, random effects they
  can cause, and how they change an object's properties.

object_property.txt
  This file gives details about what properties an object can have (apart from
  basic combat and armor class).  Every property has a code which is used
  in the game to refer to that property in some way. This means it is not
  possible to add new properties to this file and expect to have any effect,
  but it is possible to change how existing properties work.

object_power.txt
  This file contains formulas for calculating power of objects (used in 
  determining prices and generating random artifacts).  You should only change
  this file if you understand the way they are used (defined in
  src/obj-power.c).

player_timed.txt
  This file defines some of the properties of timed effects (such as haste and
  confusion) that can apply to the player.  It chiefly contains the messages
  on changes in these effects, and player attributes which prevent the effects.
  To add new timed effects or change the way existing ones operate, you will
  have to alter src/list-player-timed.h and probably other files, and 
  re-compile the game.

projection.txt
  This file contains a lot of the defining information about projections - 
  effects which can be produced at a distance by player or monsters, and 
  affecting player, monsters, objects, and/or terrain.  In particular, this
  file defines details of the effects of elemental attacks (such as fire or
  shards) and the effectiveness of corresponding player resistance.  New
  projections have to be included in src/list-projections.h, and the code to
  implement their effects put in other source files - src/project-obj.c for
  effects on objects, and other similarly-named files.

realm.txt
  This contains a small amount of information about the two current magic
  realms.


Larger changes
==============
If changing data files is not enough for you, you will need to change actual
game code and recompile it.  The first place to look is in the compiled data
files, some of which have already been mentioned:

list-dun-profiles.h    list-mon-spells.h        list-projections.h
list-effects.h         list-mon-temp-flags.h    list-randart-properties.h
list-elements.h        list-mon-timed.h         list-rooms.h
list-equip-slots.h     list-object-flags.h      list-square-flags.h
list-history-types.h   list-object-modifiers.h  list-stats.h
list-ignore-types.h    list-options.h           list-summon-types.h
list-kind-flags.h      list-origins.h           list-terrain-flags.h
list-message.h         list-parser-errors.h     list-trap-flags.h
list-mon-message.h     list-player-flags.h      list-tvals.h
list-mon-race-flags.h  list-player-timed.h

Beyond this, you will have to have some knowledge of the C programming
language, and can start making changes to the way the game runs or appears.
Many people have done this - there are over 100 variants of Angband:
http://angbandplus.github.io/AngbandPlus/
Should you get to this point, the best thing to do is to discuss your ideas on
the Angband forums at http://angband.oook.cz.  The people there are typically
keen to hear new ideas and ways to play.
