Changeset 835

Show
Ignore:
Timestamp:
04/09/08 19:32:26 (4 months ago)
Author:
takkaria
Message:

Doxygen up some of types.h.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/src/types.h

    r808 r835  
    1 /* File: types.h */ 
    2  
    3 /* 
    4  * Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke 
    5  * 
    6  * This software may be copied and distributed for educational, research, 
    7  * and not for profit purposes provided that this copyright and statement 
    8  * are included in all such copies.  Other copyrights may also apply. 
    9  */ 
    10  
    11  
    12 /* 
    13  * Note that "char" may or may not be signed, and that "signed char" 
    14  * may or may not work on all machines.  So always use "s16b" or "s32b" 
    15  * for signed values.  Also, note that unsigned values cause math problems 
    16  * in many cases, so try to only use "u16b" and "u32b" for "bit flags", 
    17  * unless you really need the extra bit of information, or you really 
    18  * need to restrict yourself to a single byte for storage reasons. 
    19  * 
    20  * Also, if possible, attempt to restrict yourself to sub-fields of 
    21  * known size (use "s16b" or "s32b" instead of "int", and "byte" instead 
    22  * of "bool"), and attempt to align all fields along four-byte words, to 
    23  * optimize storage issues on 32-bit machines.  Also, avoid "bit flags" 
    24  * since these increase the code size and slow down execution.  When 
    25  * you need to store bit flags, use one byte per flag, or, where space 
    26  * is an issue, use a "byte" or "u16b" or "u32b", and add special code 
    27  * to access the various bit flags. 
    28  * 
    29  * Many of these structures were developed to reduce the number of global 
    30  * variables, facilitate structured program design, allow the use of ascii 
    31  * template files, simplify access to indexed data, or facilitate efficient 
    32  * clearing of many variables at once. 
    33  * 
    34  * Note that certain data is saved in multiple places for efficient access, 
    35  * and when modifying the data in one place it must also be modified in the 
    36  * other places, to prevent the creation of inconsistant data. 
    37  */ 
    38  
    391#ifndef INCLUDED_TYPES_H 
    402#define INCLUDED_TYPES_H 
    413 
     4/* 
     5 * This file contains various defined types used by the game. 
     6 * 
     7 * TODO: Most of these should be elsewhere, in their own header files. 
     8 * For example, the object structs should be in object.h. 
     9 * 
     10 * Be careful when creating data structures; most of these are designed 
     11 * to be serialised to file, so be careful to use exact-size data types 
     12 * (like u32b and s32b) and not just "int"s. 
     13 */ 
    4214 
    4315/**** Available Types ****/ 
    4416 
    45  
    46 /* 
    47  * An array of 256 byte's 
    48  */ 
     17/** An array of 256 bytes */ 
    4918typedef byte byte_256[256]; 
    5019 
    51  
    52 /* 
    53  * An array of DUNGEON_WID byte's 
    54  */ 
     20/** An array of DUNGEON_WID bytes */ 
    5521typedef byte byte_wid[DUNGEON_WID]; 
    5622 
    57 /* 
    58  * An array of DUNGEON_WID s16b's 
    59  */ 
     23/** An array of DUNGEON_WID s16b's */ 
    6024typedef s16b s16b_wid[DUNGEON_WID]; 
    6125 
    …… 
    6428/** Function hook types **/ 
    6529 
     30/** Function prototype for the UI to provide to create native buttons */ 
    6631typedef int (*button_add_f)(const char *, unsigned char); 
     32 
     33/** Function prototype for the UI to provide to remove native buttons */ 
    6734typedef int (*button_kill_f)(unsigned char); 
    6835 
    …… 
    7138/**** Available Structs ****/ 
    7239 
    73  
    74 typedef struct maxima maxima; 
    75 typedef struct feature_type feature_type; 
    76 typedef struct object_kind object_kind; 
    77 typedef struct artifact_type artifact_type; 
    7840typedef struct ego_item_type ego_item_type; 
    7941typedef struct monster_blow monster_blow; 
    …… 
    10163 
    10264 
    103 /**** Available structs ****/ 
    104  
    105  
    106 /* 
    107  * Information about maximal indices of certain arrays 
    108  * Actually, these are not the maxima, but the maxima plus one 
    109  */ 
    110 struct maxima 
    111 { 
    112         u32b fake_text_size; 
    113         u32b fake_name_size; 
    114  
    115         u16b f_max;             /* Max size for "f_info[]" */ 
    116         u16b k_max;             /* Max size for "k_info[]" */ 
    117         u16b a_max;             /* Max size for "a_info[]" */ 
    118         u16b e_max;             /* Max size for "e_info[]" */ 
    119         u16b r_max;             /* Max size for "r_info[]" */ 
    120         u16b v_max;             /* Max size for "v_info[]" */ 
    121         u16b p_max;             /* Max size for "p_info[]" */ 
    122         u16b h_max;             /* Max size for "h_info[]" */ 
    123         u16b b_max;             /* Max size per element of "b_info[]" */ 
    124         u16b c_max;             /* Max size for "c_info[]" */ 
    125         u16b flavor_max; /* Max size for "flavor_info[]" */ 
    126         u16b s_max;             /* Max size for "s_info[]" */ 
    127  
    128         u16b o_max;             /* Max size for "o_list[]" */ 
    129         u16b m_max;             /* Max size for "mon_list[]" */ 
    130 }; 
    131  
    132  
    133 /* 
    134  * Information about terrain "features" 
    135  */ 
    136 struct feature_type 
    137 { 
    138         u32b name;                      /* Name (offset) */ 
    139         u32b text;                      /* Text (offset) */ 
    140  
    141         byte mimic;                     /* Feature to mimic */ 
    142  
    143         byte extra;                     /* Extra byte (unused) */ 
    144  
    145         s16b unused;            /* Extra bytes (unused) */ 
    146  
    147  
    148         byte d_attr;            /* Default feature attribute */ 
    149         char d_char;            /* Default feature character */ 
    150  
    151  
    152         byte x_attr;            /* Desired feature attribute */ 
    153         char x_char;            /* Desired feature character */ 
    154 }; 
    155  
    156  
    157 /* 
    158  * Information about object "kinds", including player knowledge. 
    159  * 
    160  * Only "aware" and "tried" are saved in the savefile 
    161  */ 
    162 struct object_kind 
    163 { 
    164         u32b name;                      /* Name (offset) */ 
    165         u32b text;                      /* Text (offset) */ 
    166  
    167         byte tval;                      /* Object type */ 
    168         byte sval;                      /* Object sub type */ 
    169  
    170         s16b pval;                      /* Object extra info */ 
    171  
    172         s16b to_h;                      /* Bonus to hit */ 
    173         s16b to_d;                      /* Bonus to damage */ 
    174         s16b to_a;                      /* Bonus to armor */ 
    175  
    176         s16b ac;                        /* Base armor */ 
    177  
    178         byte dd, ds;            /* Damage dice/sides */ 
    179  
    180         s16b weight;            /* Weight */ 
    181  
    182         s32b cost;                      /* Object "base cost" */ 
    183  
    184         u32b flags1;            /* Flags, set 1 */ 
    185         u32b flags2;            /* Flags, set 2 */ 
    186         u32b flags3;            /* Flags, set 3 */ 
    187  
    188         byte alloc_prob;        /* Allocation: commonness */ 
    189         byte alloc_min;         /* Highest normal dungeon level */ 
    190         byte alloc_max;         /* Lowest normal dungeon level */ 
    191         byte level;                     /* Level */ 
    192  
    193  
    194         byte d_attr;            /* Default object attribute */ 
    195         char d_char;            /* Default object character */ 
    196  
    197         byte x_attr;            /* Desired object attribute */ 
    198         char x_char;            /* Desired object character */ 
    199  
    200  
    201         u16b effect;            /* Effect this item produces */ 
    202         u16b time_base;         /* Recharge time (if appropriate) */ 
    203         byte time_dice; 
    204         byte time_sides; 
    205  
    206         byte charge_base;       /* Charge base */ 
    207         byte charge_dd; 
    208         byte charge_ds; /* Charge dice/sides */ 
    209  
    210         byte gen_mult_prob;     /* Probability of generating more than one */ 
    211         byte gen_dice;          /* Average number to generate - dice rolled */ 
    212         byte gen_side;          /* Average number to generate - dice sides */ 
    213  
    214  
    215         u16b flavor;            /* Special object flavor (or zero) */ 
    216         u16b note;          /* Autoinscription field (later) */ 
    217  
    218         bool aware;             /* The player is "aware" of the item's effects */ 
    219         bool tried;             /* The player has "tried" one of the items */ 
    220  
    221         bool squelch;           /* Squelch this item? */ 
    222         bool everseen;          /* Used to despoilify squelch menus */ 
    223 }; 
    224  
    225  
    226  
    227 /* 
    228  * Information about "artifacts". 
    229  * 
    230  * Note that the save-file only writes "cur_num" to the savefile. 
    231  * 
    232  * Note that "max_num" is always "1" (if that artifact "exists") 
    233  */ 
    234 struct artifact_type 
    235 { 
    236         u32b name;                      /* Name (offset) */ 
    237         u32b text;                      /* Text (offset) */ 
    238  
    239         byte tval;                      /* Artifact type */ 
    240         byte sval;                      /* Artifact sub type */ 
    241  
    242         s16b pval;                      /* Artifact extra info */ 
    243  
    244         s16b to_h;                      /* Bonus to hit */ 
    245         s16b to_d;                      /* Bonus to damage */ 
    246         s16b to_a;                      /* Bonus to armor */ 
    247  
    248         s16b ac;                        /* Base armor */ 
    249  
    250         byte dd, ds;            /* Damage when hits */ 
    251  
    252         s16b weight;            /* Weight */ 
    253  
    254         s32b cost;                      /* Artifact "cost" */ 
    255  
    256         u32b flags1;            /* Artifact Flags, set 1 */ 
    257         u32b flags2;            /* Artifact Flags, set 2 */ 
    258         u32b flags3;            /* Artifact Flags, set 3 */ 
    259  
    260         byte level;                     /* Artifact level */ 
    261         byte rarity;            /* Artifact rarity */ 
    262  
    263         byte cur_num;           /* Number created (0 or 1) */ 
    264         byte max_num;           /* Unused (should be "1") */ 
    265  
    266         u16b effect;            /* Effect this item produces */ 
    267         u32b effect_msg;        /* Effect message (offset) into text */ 
    268         u16b time_base;         /* Recharge time (if appropriate) */ 
    269         byte time_dice; 
    270         byte time_sides; 
    271 }; 
     65/** 
     66 * Information about maximal indices of certain arrays. 
     67 * 
     68 * These are actually not the maxima, but the maxima plus one, because of 
     69 * 0-based indexing issues. 
     70 */ 
     71typedef struct 
     72{ 
     73        u32b fake_text_size;  /**< Max size of all descriptions read in from lib/edit/* */ 
     74        u32b fake_name_size;  /**< Max size of all names read in from lib/edit/* */ 
     75 
     76        u16b f_max;       /**< Maximum number of terrain features */ 
     77        u16b k_max;       /**< Maximum number of object base kinds */ 
     78        u16b a_max;       /**< Maximum number of artifact kinds */ 
     79        u16b e_max;       /**< Maximum number of ego-item kinds */ 
     80        u16b r_max;       /**< Maximum number of monster races */ 
     81        u16b v_max;       /**< Maximum number of vault kinds */ 
     82        u16b p_max;       /**< Maximum number of player races */ 
     83        u16b h_max;       /**< Maximum number of chained player history entries */ 
     84        u16b b_max;       /**< Maximum number of shop owners per store kind */ 
     85        u16b c_max;       /**< Maximum number of player classes */ 
     86        u16b flavor_max;  /**< Maximum number of item flavour kinds */ 
     87        u16b s_max;       /**< Maximum number of magic spells */ 
     88 
     89        u16b o_max;       /**< Maximum number of objects on a given level */ 
     90        u16b m_max;       /**< Maximum number of monsters on a given level */ 
     91} maxima; 
     92 
     93 
     94/** 
     95 * Information about terrain features. 
     96 * 
     97 * At the moment this isn't very much, but eventually a primitive flag-based 
     98 * information system will be used here. 
     99 */ 
     100typedef struct 
     101{ 
     102        u32b name;    /**< (const char *) feature_type::name + f_name = Name */ 
     103        u32b text;    /**< (const char *) feature_type::text + f_text = Description (unused) */ 
     104 
     105        byte mimic;   /**< Feature to mimic */ 
     106 
     107        byte extra;   /**< Unused */ 
     108        s16b unused;  /**< Unused */ 
     109 
     110        byte d_attr;  /**< Default feature attribute */ 
     111        char d_char;  /**< Default feature character */ 
     112 
     113        byte x_attr;  /**< Desired feature attribute (set by user/pref file) */ 
     114        char x_char;  /**< Desired feature character (set by user/pref file) */ 
     115} feature_type; 
     116 
     117 
     118/** 
     119 * Information about object kinds, including player knowledge. 
     120 * 
     121 * TODO: split out the user-changeable bits into a separate struct so this 
     122 * one can be read-only. 
     123 */ 
     124typedef struct 
     125{ 
     126        /** Constants **/ 
     127 
     128        u32b name;     /**< (const char *) object_kind::name + k_name = Name */ 
     129        u32b text;     /**< (const char *) object_kind::text + k_text = Description  */ 
     130 
     131        byte tval;     /**< General object type (see TV_ macros) */ 
     132        byte sval;     /**< Object sub-type (see SV_ macros) */ 
     133        s16b pval;     /**< Power for any flags which need it */ 
     134 
     135        s16b to_h;     /**< Bonus to-hit */ 
     136        s16b to_d;     /**< Bonus to damage */ 
     137        s16b to_a;     /**< Bonus to armor */ 
     138        s16b ac;       /**< Base armor */ 
     139 
     140        byte dd;       /**< Damage dice */ 
     141        byte ds;       /**< Damage sides */ 
     142        s16b weight;   /**< Weight, in 1/10lbs */ 
     143 
     144        s32b cost;     /**< Object base cost */ 
     145 
     146        u32b flags1;   /**< Flags, set 1 (see TR1_ macros) */ 
     147        u32b flags2;   /**< Flags, set 2 (see TR2_ macros) */ 
     148        u32b flags3;   /**< Flags, set 3 (see TR3_ macros) */ 
     149 
     150        byte d_attr;   /**< Default object attribute */ 
     151        char d_char;   /**< Default object character */ 
     152 
     153        byte alloc_prob;   /**< Allocation: commonness */ 
     154        byte alloc_min;    /**< Highest normal dungeon level */ 
     155        byte alloc_max;    /**< Lowest normal dungeon level */ 
     156        byte level;        /**< Level */ 
     157 
     158        u16b effect;       /**< Effect this item produces (effects.c) */ 
     159        u16b time_base;    /**< Recharge time (if appropriate) */ 
     160        byte time_dice;    /**< Randomised recharge time dice */ 
     161        byte time_sides;   /**< Randomised recharge time sides */ 
     162 
     163        byte charge_base;  /**< Non-random initial charge base */ 
     164        byte charge_dd;    /**< Randomised initial charge dice */ 
     165        byte charge_ds;    /**< Randomised initial charge sides */ 
     166 
     167        byte gen_mult_prob; /**< Probability of generating more than one */ 
     168        byte gen_dice;      /**< Number to generate dice */ 
     169        byte gen_side;      /**< Number to generate sides */ 
     170 
     171        u16b flavor;        /**< Special object flavor (or zero) */ 
     172 
     173 
     174        /** Game-dependent **/ 
     175 
     176        byte x_attr;   /**< Desired object attribute (set by user/pref file) */ 
     177        char x_char;   /**< Desired object character (set by user/pref file) */ 
     178 
     179        /** Also saved in savefile **/ 
     180 
     181        u16b note;     /**< Autoinscription quark number */ 
     182 
     183        bool aware;    /**< Set if player is aware of the kind's effects */ 
     184        bool tried;    /**< Set if kind has been tried */ 
     185 
     186        bool squelch;  /**< Set if kind should be squelched */ 
     187        bool everseen; /**< Set if kind has ever been seen (to despoilify squelch menus) */ 
     188} object_kind; 
     189 
     190 
     191 
     192/** 
     193 * Information about artifacts. 
     194 * 
     195 * Note that ::cur_num is written to the savefile. 
     196 * 
     197 * TODO: Fix this max_num/cur_num crap and just have a big boolean array of 
     198 * which artifacts have been created and haven't, so this can become read-only. 
     199 */ 
     200typedef struct 
     201{ 
     202        u32b name;    /**< (const char *) artifact_type::name + a_name = Name */ 
     203        u32b text;    /**< (const char *) artifact_type::text + a_text = Description  */ 
     204 
     205        byte tval;    /**< General artifact type (see TV_ macros) */ 
     206        byte sval;    /**< Artifact sub-type (see SV_ macros) */ 
     207        s16b pval;    /**< Power for any flags which need it */ 
     208 
     209        s16b to_h;    /**< Bonus to hit */ 
     210        s16b to_d;    /**< Bonus to damage */ 
     211        s16b to_a;    /**< Bonus to armor */ 
     212        s16b ac;      /**< Base armor */ 
     213 
     214        byte dd;      /**< Base damage dice */ 
     215        byte ds;      /**< Base damage sides */ 
     216 
     217        s16b weight;  /**< Weight in 1/10lbs */ 
     218 
     219        s32b cost;    /**< Artifact (pseudo-)worth */ 
     220 
     221        u32b flags1;  /**< Flags, set 1 (see TR1_ macros) */ 
     222        u32b flags2;  /**< Flags, set 2 (see TR2_ macros) */ 
     223        u32b flags3;  /**< Flags, set 3 (see TR3_ macros) */ 
     224 
     225        byte level;   /**< Minimum depth artifact can appear at */ 
     226        byte rarity;  /**< Artifact rarity */ 
     227 
     228        byte max_num; /**< Unused (should be "1") */ 
     229        byte cur_num; /**< Number created (0 or 1) */ 
     230 
     231        u16b effect;     /**< Artifact activation (see effects.c) */ 
     232        u32b effect_msg; /**< (const char *) artifact_type::effect_msg + a_text = Effect message */ 
     233        u16b time_base;  /**< Recharge time (if appropriate) */ 
     234        byte time_dice;  /**< Randomised recharge time dice */ 
     235        byte time_sides; /**< Randomised recharge time sides */ 
     236 
     237} artifact_type; 
    272238 
    273239 
    …… 
    359325 
    360326        s16b power;                             /* Monster power */ 
    361          
     327 
    362328#ifdef ALLOW_TEMPLATES_PROCESS 
    363329 
    …… 
    390356        byte max_num;                   /* Maximum population allowed per level */ 
    391357        byte cur_num;                   /* Monster population on current level */ 
    392  
    393358}; 
    394359 
    …… 
    772737        u16b sense_div;         /* Pseudo-id divisor */ 
    773738 
    774         start_item start_items[MAX_START_ITEMS];/* The starting inventory */ 
     739        start_item start_items[MAX_START_ITEMS];/**< The starting inventory */ 
    775740 
    776741        player_magic spells; /* Magic spells */