1 /* $Header: /home/jcb/MahJong/newmj/RCS/player.h,v 12.0 2009/06/28 20:43:13 jcb Rel $ 2 * player.h 3 * Contains datatypes representing the state of players. 4 */ 5 /****************** COPYRIGHT STATEMENT ********************** 6 * This file is Copyright (c) 2000 by J. C. Bradfield. * 7 * Distribution and use is governed by the LICENCE file that * 8 * accompanies this file. * 9 * The moral rights of the author are asserted. * 10 * * 11 ***************** DISCLAIMER OF WARRANTY ******************** 12 * This code is not warranted fit for any purpose. See the * 13 * LICENCE file for further information. * 14 * * 15 *************************************************************/ 16 17 #ifndef PLAYER_H_INCLUDED 18 #define PLAYER_H_INCLUDED 19 20 #include "tiles.h" 21 22 /* Repeated from game.h. Eventually, this should be a game option, 23 if we ever want to play three handed */ 24 #define NUM_SEATS 4 25 26 /* A TileSet represents a (potentially) declared set. It is represented 27 as the type, which may be Empty, Chow, Pung, Kong, ClosedPung 28 (only really used at the end), or ClosedKong. 29 Also Pair and ClosedPair (for scoring). 30 The second element is a Tile, which is the tile for Pungs and Kongs, 31 and the first tile for chows. 32 To account for the Millington rule whereby a claimed kong counts 33 as concealed for doubling purposes, there is a third element 34 annexed which is true if a kong was made by adding to an existing pung. 35 Note: the value of the annexed field is only meaningful if the type 36 is Kong. 37 */ 38 39 typedef enum { 40 Empty = 0, 41 Chow = 1, 42 Pung = 2, 43 Kong = 3, 44 ClosedPung = 4, 45 ClosedKong = 5, 46 ClosedChow = 6, /* used in scoring */ 47 Pair = 7, /* used in scoring etc */ 48 ClosedPair = 8 49 } TileSetType; 50 51 typedef struct _TileSet { 52 TileSetType type; 53 Tile tile; 54 int annexed; 55 } TileSet; 56 57 /* Pointer to TileSet */ 58 typedef TileSet *TileSetP; 59 60 /* The PlayerOption type names options that the player can ask 61 the controller to apply. 62 */ 63 typedef enum { 64 /* make-enums sub { $_[0] =~ s/^PO//; } */ 65 POUnknown = 0, 66 POInfoTiles, /* should we be sent InfoTiles messages at every event ? */ 67 PODelayTime, /* A time in deciseconds. The controller is requested to 68 leave at least this time between successive actions 69 (where an action is a tile movement). This might be 70 just to slow robot players down to human speed, or 71 to allow time for animation. 72 The controller does not have to take any notice! */ 73 POLocalTimeouts, /* The client wishes to handle timeouts locally */ 74 PONumOptions /* number of options available */ 75 } PlayerOption; 76 77 78 /* num_tiles_in_set: takes a TileSetP and returns the number of tiles 79 in it. 80 */ 81 82 int num_tiles_in_set(TileSetP tp); 83 84 /* The Player datatype represents the state of a player. 85 See internal comments for elucidation. 86 The structure is public for convenience, but should be 87 considered read-only, and modified by the provided functions. 88 */ 89 90 typedef struct _Player { 91 int id; /* unique identifier assigned by the master controller, 92 and used in communication. Always non-zero for a real player. */ 93 char *name; /* the name of this player */ 94 TileWind wind; /* which wind this player currently is */ 95 int num_concealed; /* how many concealed tiles */ 96 #define MAX_CONCEALED 14 97 Tile concealed[MAX_CONCEALED]; /* the concealed tiles (if known) */ 98 int discard_hint; /* this is used by programs to tell player_discards_tile 99 which tile to discard, when the order of identical 100 tiles is important, as is the case when maintaining 101 a display of the hand according to the user's 102 preferences. */ 103 #define MAX_TILESETS 7 /* may have up to seven pairs. 104 Note: this happens even without the seven 105 pairs hand, since the player_can_mah_jong 106 function blindly looks for pairs. Perhaps 107 it shouldn't. */ 108 TileSet tilesets[MAX_TILESETS]; /* exposed tiles */ 109 int num_specials; /* number of flowers and seasons held */ 110 Tile specials[8]; /* flowers and seasons */ 111 unsigned int flags; /* for bit definitions, see below */ 112 unsigned int dflags[NUM_SEATS]; /* see below */ 113 int cumulative_score; /* score so far in the game (excluding current hand)*/ 114 int hand_score; /* score in this hand. Set to -1 during hand. */ 115 char *err; /* used to return error messages by methods. Value is 116 only meaningful after a method has failed (including 117 test functions returning false). */ 118 void *userdata; /* for client programs */ 119 } Player ; 120 121 /* mask bit numbers for player flags */ 122 typedef enum { 123 Hidden, /* true if we can't see the player's hand */ 124 MahJongged, /* true if this hand has gone mah jongg */ 125 HandDeclared, /* true if the hand has been declared, and accordingly 126 the "concealed" tiles are no longer. Implies Hidden is 127 false */ 128 /* the next three flags are used to handle calling declarations */ 129 /* the next flag is set internally by the player module */ 130 NoDiscard, /* true before the first discard */ 131 /* the next two flags must be set by the user of this module, 132 and are cleared by the player_newhand function */ 133 OriginalCall, /* true if the player has made an original call */ 134 Calling, /* true if the player has made a calling declaration 135 (when implemented) */ 136 } PlayerFlags; 137 138 139 /* pointer to Player. In order to discourage people from modifying 140 players directly, this is actually declared as const, unless this 141 is the player module being compiled. 142 */ 143 #ifdef PLAYER_C 144 typedef Player *PlayerP; 145 #else 146 typedef const Player *PlayerP; 147 #endif 148 149 /* given a pointer to player, test the flag */ 150 /* Cast to avoid problems */ 151 #define pflag(p,f) (p->flags & (1 << f)) 152 /* set, clear */ 153 #define psetflag(p,f) (((Player *)p)->flags |= (1 << f)) 154 #define pclearflag(p,f) (((Player *)p)->flags &= ~(1 << f)) 155 156 157 /* The dflags field of the player is used for keeping track of 158 dangerous discards. The element of the player's own seat records 159 whether the player's hand is dangerous: the elements corresponding 160 to the other players record when another player supplies a dangerous 161 discard. 162 NOTE: these flags are maintained by the game module, and then 163 only if checking is on. 164 NOTE: these flags are all related and may be combined. 165 They are therefore given as actual bits, so they can be combined 166 with & and |. 167 */ 168 /* The dangerous hands for letting off a cannon */ 169 typedef enum { 170 DangerBamboo=1, 171 DangerCharacter=2, 172 DangerCircle=4, 173 DangerWind=8, 174 DangerDragon=16, 175 DangerHonour=32, 176 DangerGreen=64, 177 DangerTerminal=128, 178 DangerEnd=256 /* when the wall is nearly empty */ 179 } DangerSignals; 180 181 #define pdflag(p,s,f) (p->dflags[s] & f) 182 /* set, clear */ 183 #define psetdflags(p,s,f) (((Player *)p)->dflags[s] |= f) 184 #define pcleardflags(p,s,f) (((Player *)p)->dflags[s] &= ~f) 185 #define presetdflags(p,s) (((Player *)p)->dflags[s] = 0) 186 187 188 189 /* Some of these functions return 1 for success and 0 for failure. 190 In the case of failure, they leave the argument player unchanged. 191 */ 192 193 /* initialize_player: takes a PlayerP and fills in the fields 194 with initial values; most are zero, but the hand_score is set to -1. 195 */ 196 void initialize_player(PlayerP p); 197 198 /* player_newhand: sets up the player for the start of a new hand. 199 The given wind is the wind of this player. 200 (N.B. This is a TileWind, not a seat.) 201 */ 202 void player_newhand(PlayerP p,TileWind w); 203 204 /* copy_player: copy old player into new (which must already 205 be allocated). Returns new. 206 */ 207 208 PlayerP copy_player(PlayerP newp,const PlayerP oldp); 209 210 /* set_player_id: sets the id of a player. Complains if the player 211 already has an id (but continues). 212 */ 213 void set_player_id(PlayerP p, const int id); 214 215 /* set_player_name: sets the name of a player. The argument string 216 is copied. Warning: any existing name is freed. 217 The name may be NULL, which is not the same as an empty string. 218 */ 219 void set_player_name(PlayerP p, const char *n); 220 221 /* set_player_cumulative_score: 222 sets the score of the player */ 223 void set_player_cumulative_score(PlayerP p, int s); 224 225 /* change_player_cumulative_score: 226 add d to the player's score */ 227 void change_player_cumulative_score(PlayerP p, int d); 228 229 /* set_player_hand_score: 230 set the hand_score field. */ 231 void set_player_hand_score(PlayerP p, int h); 232 233 void set_player_userdata(PlayerP p, void *ud); 234 235 /* utility to count occurrences of tile in player's hand */ 236 237 int player_count_tile(PlayerP p, Tile t); 238 239 /* player_draws_tile: first arg is a PlayerP. 240 Second argument is a tile; it is HiddenTile if we can't see it. 241 Returns 1 on success. 242 */ 243 244 int player_draws_tile(PlayerP p, Tile t); 245 246 /* player_draws_loose_tile: first arg is a PlayerP. 247 Second argument is a tile; it is HiddenTile if we can't see it. 248 Returns 1 on success. 249 */ 250 251 int player_draws_loose_tile(PlayerP p, Tile t); 252 253 /* player_declares_special: the player declares the special tile 254 given as the second argument, which is removed from the concealed 255 tiles and added to the special tiles. The player is given the tile 256 specified by the third argument to replace the special; this is 257 HiddenTile if we cannot observe it. 258 May be called on players that are known or hidden. 259 */ 260 int player_declares_special(PlayerP p, Tile spec); 261 262 /* player_can_declare_special: just tests for legality of this move. 263 Should only be called on players that are known. 264 */ 265 int player_can_declare_special(PlayerP p, Tile spec); 266 267 /* the following functions declare sets. If they leave the player 268 with no concealed tiles, so that the hand is complete, they set 269 the HandDeclared flag. 270 */ 271 272 /* player_pungs: player takes the tile, and uses it to form a pung. 273 */ 274 int player_pungs(PlayerP p, Tile d); 275 276 int player_can_pung(PlayerP p, Tile d); 277 278 /* player_pairs: player takes the tile, and uses it to form a pair. 279 Only used after mahjong. 280 */ 281 int player_pairs(PlayerP p, Tile d); 282 283 int player_can_pair(PlayerP p, Tile d); 284 285 /* player_kongs: player takes tile, forms kong */ 286 int player_kongs(PlayerP p, Tile d); 287 288 int player_can_kong(PlayerP p, Tile d); 289 290 /* player_declares_closed_kong: player declares a closed kong 291 of d. 292 NOTE that these functions do not check whether it's player's turn, 293 since they do not have access to that information. 294 */ 295 int player_declares_closed_kong(PlayerP p, Tile d); 296 297 int player_can_declare_closed_kong(PlayerP p, Tile d); 298 299 /* player_adds_to_pung: player has drawn t, and adds it to an existing 300 open pung. 301 */ 302 int player_adds_to_pung(PlayerP p, Tile t); 303 304 int player_can_add_to_pung(PlayerP p, Tile t); 305 306 /* player_kong_robbed: the player has formed a kong of t, and it is robbed */ 307 int player_kong_is_robbed(PlayerP p, Tile t); 308 309 /* player_forms_closed_pung: player has a pung of d. This is 310 used only when preparing hands for scoring. */ 311 312 int player_forms_closed_pung(PlayerP p, Tile d); 313 314 int player_can_form_closed_pung(PlayerP p, Tile d); 315 316 /* player_forms_closed_pair: player has a pair of d. This is 317 used only when preparing hands for scoring. */ 318 319 int player_forms_closed_pair(PlayerP p, Tile d); 320 321 int player_can_form_closed_pair(PlayerP p, Tile d); 322 323 /* Chow declarations have to say where the claimed tile is being 324 inserted. This is partly so that it's easy to check, and partly 325 because some esoteric scoring rules need this information. 326 327 The final argument is Lower, Middle, or Upper, depending on where 328 the tile d is to go in the chow. 329 330 The testing functions will accept an argument of AnyPos, in which 331 case they will iterate over the three possible values. 332 333 NOTE that these functions do not check that it's player's turn. 334 */ 335 336 /* NOTE NOTE: these values are assumed, and must not be changed. 337 (Because a chow is defined by its lower tile, so 338 claimedtile = chowdefiningtile + chowposition.) 339 The AnyPos value is defined to be MaxTile, so that adding it 340 or subtracting it from a Tile is guaranteed to produce an error. 341 */ 342 typedef enum { 343 Lower = 0, 344 Middle = 1, 345 Upper = 2, 346 AnyPos = MaxTile 347 } ChowPosition; 348 349 int player_chows(PlayerP p, Tile d, ChowPosition r); 350 351 int player_can_chow(PlayerP p, Tile d, ChowPosition r); 352 353 /* used only in scoring. Although in the client/server protocol, 354 a closed chow is always specified as Lower, in evaluating hands 355 it is often wanted to check for closed chows with a given tile 356 in a given position. Therefore these functions take a position. 357 */ 358 359 int player_forms_closed_chow(PlayerP p, Tile d, ChowPosition r); 360 361 int player_can_form_closed_chow(PlayerP p, Tile d, ChowPosition r); 362 363 /* tests whether a player has a mah-jong hand. The d argument is 364 the discard tile available to the player, or HiddenTile if the 365 player already has 14 tiles. 366 The third arg says which special hands should be tested for. 367 Currently, thirteen wonders is always allowed, so the only 368 possible value here is 0 or seven pairs. 369 */ 370 typedef enum { 371 MJSevenPairs = 1 372 } MJSpecialHandFlags; 373 374 int player_can_mah_jong(PlayerP p, Tile d, MJSpecialHandFlags flags); 375 376 /* tests whether a player has the thirteen unique wonders. 377 This is included in the above test, but is separately 378 exported as a convenience. */ 379 int player_can_thirteen_wonders(PlayerP p, Tile d); 380 381 /* set the discard_hint: which concealed tile should be discarded 382 (as opposed to the default choice of the first tile that is right). 383 Values are -1 for no hint, or 0..num_concealed-1. 384 The discard_hit is cleared on discard. 385 */ 386 int player_set_discard_hint(PlayerP p, int n); 387 388 /* player discards a tile */ 389 int player_discards(PlayerP p, Tile t); 390 391 int player_can_discard(PlayerP p, Tile t); 392 393 /* utility to sort the concealed tiles. This sorts the tiles into 394 increasing order; however, the only safe assumptions about the values 395 of the tiles are those allowed by tiles.h. 396 Thus it *is* safe to assume that tile appear in increasing value and that 397 tiles of the same suit appear together; but it is *not* safe to assume 398 the suits appear in any particular order. 399 */ 400 void player_sort_tiles(PlayerP p); 401 402 /* utility to exchange two concealed tiles. Moves the tile in position old 403 to position new */ 404 int player_reorder_tile(PlayerP p, int old, int new); 405 406 /* player_print_tiles: puts into buf, which is required to be 407 at least 80 characters, a human readable representation of 408 the player's tiles. Each tile is represented by its code, and 409 the hand is represented as: 410 space separated concealed tiles; 411 ' * '; 412 space separated tilesets, represented as tile-tile 413 for exposed sets and tile+tile for closed sets; 414 ' * '; 415 space separated specials. 416 If the third argument is true, then the concealed tiles 417 are printed as blanks. This happens anyway if they are hidden 418 in the player structure. 419 */ 420 void player_print_tiles(char *buf, PlayerP p, int hide); 421 422 /* set_player_tiles: converse of the above. Takes a string description 423 of the player's tiles, and forces the Player to agree. 424 Forces the Hidden flag on or off if appropriate. 425 Returns 1 on success, 0 on error. If error, all bets are off. 426 */ 427 int set_player_tiles(PlayerP p, char *desc); 428 429 /* player_shows_tiles: takes a string representation of a tile 430 list (as above), and sets the player's concealed tiles to it. 431 Also sets the HandDeclared flag. 432 */ 433 int player_shows_tiles(PlayerP p, char *desc); 434 435 /* player_swap_tile: swaps the oldtile for the newtile in the 436 concealed tiles. Only used in testing, of course */ 437 int player_swap_tile(PlayerP p, Tile oldtile, Tile newtile); 438 439 /* tileset_string: utility function, returning the printed 440 representation of a tileset, as above. N.B. this function 441 returns a string in static storage, which will be overwritten 442 on the next call. 443 */ 444 char *tileset_string(TileSetP tp); 445 446 /* diagnostic function: print a text representation of the player's 447 state into a (possibly static) buffer and return it */ 448 char *player_print_state(PlayerP p); 449 450 /* now import the functions for printing and scanning enums */ 451 #include "player-enums.h" 452 453 #endif /* PLAYER_H_INCLUDED */ 454