(This is the text version of the VariantsHOWTO; the reference versions is the HTML one) Creating variants for the Diplomacy judge v 0.33 [1]Christophe Courtois ([2]christophe@courtois.cc[3]) & [4]Millis Miller (millis@faztek.org) _________________________________________________________________ This documentation is not finished and may contain many errors. _________________________________________________________________ [5]1 Introduction [6]1.1 History [7]1.2 Last version [8]1.3 Why? [9]2 What you can and must do [10]2.1 Possibilities [11]2.3. Variant options [12]3 Data to provide [13]3.1. Map files [14]3.1.1 Declaration of lands and centers [15]3.1.2 Movements [16]3.1.3 ordering for summaries (optional) [17]3.1.4 Other optional data [18]3.2 Seed file [19]3.2.1 Seed file format [20]3.2.2 When units do not begin on home centers [21]3.2.3 Special seed files (seed_b, seed_w...) [22]3.2.4 In the code [23]3.3 Info files [24]3.4 Variant.h [25]4 Examples [26]4.1 H32 (Hundred) Wings [27]4.2 Fleet in Marseille [28]4.3 Switzerland [29]4.4 Chess [30]5 floc.net [31]6 Mapmaker [32]7 Addmap [33]8 Automatic tests [34]9 Troubleshooting [35]10 Integration in the official judge source [36]11 Moving variants between judges [37]12 Misc [38]12.1 The author [39]12.2 Thanks [40]12.3 Copyright and boring stuff _________________________________________________________________ 1 Introduction 1.1 History * 0.2 : Mar-Apr 2003 * 0.31 : July 2003 First updates * 0.32 : 23^rd July 2003 Updated and spelling corrections (Millis Miller) * 0.33 : 27^th July 2003 Update of the updates 1.2 Last version This is a guide which aims to help people creating variants for the Diplomacy judge. The reference version is the HTML version. The text should be automatically generated against the HTML. Anyway, the last version of this file should always be in the last CVS snapshot of the judge at [41]http://www.njudge.org/. 1.3 Why? There seems to lack documentation on how to make a variant. [42]David Norman provides some useful help but I think that many things shoudn't need to go through him now that everyone can have a judge at home. I'll try to sum up here most knowledge on variants creation, beginning by the basic ones, made from existing maps. I won't cover variants with new rules not yet implemented in the judge. All this was tested on a njudge v. 1.4.1 from June 2003. 2 What you can and must do 2.1 Possibilities Trivial "almost-variants" without recompilation needed are: * Add maps for wings or blind options to existing variants (see [43]Special seed files). * Change start units positions of existing variants (see [44]Seed files), but it will not be compatible with the 'official' set of variants. Easy variants covered here are: * Variants with an existing map slightly modified * Variants with a simple map * Variants with new powers A bit more difficult, which will lead you to use MapMaker and perhaps contacting David Norman: * Variants with totally new and complex maps You'll have to understand the code of the judge yourself for changing any rule... And creating the map files and pictures if currently out of subject. 2.3. Variant options There are variants based on maps, like standard, modern, h32... , and there are the variant options or modifiers: Wings, Gunboat, Blind, Shorthand. See the info file for each of them, but basically Shorthand and Gunboat only affect press, while Blind and Wings may have impact on map files. 3 Data to provide (Warning: Some file names changed with judge 1.4; many old judges will use numbers instead of variant name as an extension). For a complete new variant, you MUST provide this: * Map file: this lists the territories, the way they communicate with each other, the order which must be used in summary reports. Example: data/map, data/map.loeb9 * Seed file : this lists the units beginning positions and what are the home centers. Example: data/seed.loeb9 * Report file : this file is sent at game start, giving the initial positions. Example: data/report.loeb9 You MUST modify theses files in the source code of the judge: * variant.h * variant.c And you MAY provide these files, but the judge will work without them. They will be necessary for the players though. * Info file: It contains the differences between the standard game and the variant. Example: data/info.wings, data/info.h32 * Rules file: Only if you create a whole new game. Example: data/rules.machiavelli There are some additional files to modify to package a new variant into the official judge, see later. 3.1. Map files A map file is in the data/ subdirectory. The name is map.. The format is fully described by a document from Sergio Lidsell that is part of the judge package: [45]njudgemapdatahowto.htm. Following are just examples from the standard map to sum it up. 3.1.1 Declaration of lands and centers Switzerland, (Neutral land) l swi switz swiss (Accepted order abbreviations) Adriatic Sea, (Sea) w adr adriatic Ankara, (Home center of T) T ank ankar Belgium, (Neutral land center but allowing convoys) xw bel belgi 3.1.2 Movements A line must be created for each movement type allowed for a province, land routes (mv) and sea routes (xc). If a province has only one specified, it is not reachable by the other (i.e. A land-locked province such as Munich only has a land route specified). Fleets use sea-routes (which also specify allowed coasts if relevant) and all non-fleet units use land routes. swi-mv: (Switzerland, no possible move) swi adr-xc: (Between a coast and its neighbours) alb apu ven tri ion bud-mv: (Between a land and its neighbours) vie gal rum ser tri con-mv: con-xc: (Province with land movement and sea movement) bul ank smy bul/sc bul/ec bla ank smy aeg 3.1.3 ordering for summaries (optional) This specifies how centres are groups in the summary report ('summary '). They can be in any arbitrary order desired, thoguh it is normal to group them by home-owner and geographical proximity to aid legibility. Center order for summary report: ven rom nap tun edi lon lvp bre par mar por spa bel hol mun kie ber den swe nor stp war mos sev con ank smy bul rum gre ser bud vie tri #End of center ordering 3.1.4 Other optional data Hong Kong flag, railways, and so on, are described in [46]njudgemapdatahowto.htm. For a good example, see map.colonial. 3.2 Seed file 3.2.1 Seed file format The seed file is in the data/ subdirectory. The name is seed.. The first line contains the first game season. This is a redundancy with what is in variant.c, but both sources must give the same value. If the seed file and variant.c don't match on the start season, the judge will crash at the first resolution of orders. (Even if the test disappears some day, the file format probably won't change to preserve variant files compatibility with [DEL: obsolete :DEL] old judges). Then follow the positions of the units at the start of the game for each power, and the centers that each player possess at the beginning. On the standard map you obtain (file seed.standard): S1901M A: A Budapest A: A Vienna A: F Trieste E: A Liverpool E: F Edinburgh ... T: F Ankara -1 Null ownership/contested record will initialize from the map data. -1 The last line indicates the start position of each power. In the standard game and most variants, it is not given, and the home centers are the one occupied by units. 3.2.2 When units do not begin on home centers Another example is the seed for the Chaos variant (seed.chaos) : F1900B -1 ....A....BC..DEF..GH.I....J...K..LN.PQ.RST...U.V..W.X.YZ0..1234.56.... 78.9.. -1 There is no units at the beginning. Each character is a territory. Each dot is one without an owner, and letters and numbers indicate the power who possess the center at the beginning. There is no list of units ready to begin, and the first season is a build phase, so the players must begin by building a unit. For the last version of the Hundred variant, called h32 (seed.h32) we have: S1425M B: A Dijon B: A Flanders B: A Luxembourg B: F Holland E: A Calais E: A Guyenne E: A Normandy E: F English Channel E: F London F: A Dauphine F: A Orleanais F: A Paris F: A Toulouse F: A Provence -1 ........E...FEB.B.EB..E.B..E..FF.......F. -1 In this seed, France begins with 5 units on the board, but possess only 4 centers, and will have to gain a center in the first year to avoid to disband a unit. 3.2.3 Special seed files (seed_b, seed_w...) There are special seed files for the special variants options (wings, gunboat...). For example, a variant with the wings option can have a seed file ending by _w. If such a file does not exist, the standard seed file is used, and the game begins without any wing units on the board. The only seed file with such a property currently in the source tree is seed_w.modern, the wings version of the Modern variant. It is the same file as seed.modern, except that some units at the beginning are wings (see info.wings): B: W London F: W Bordeaux There is no example of a seed_b or seed_bw file, although all is in place in the judge code to use it (it may be removed in the future). There is in any case little point in having special seed files for Blind variants... 3.2.4 In the code The part of the code responsible for opening the seed file is ml_signon.c. 3.3 Info files The info. contains all informations on your variant: differences against the standard map, new units or territory, special territories, starting positions and home centers, default variant modifiers (wings...), supply centers and how many must be won, who made the variant... See other info files as example. They are used as reference files for the players, providing information about the variant, and are retrieved with the judge command 'get info.'. The judge itself doesn't need them. 3.4 Variant.c and variant.h These two files are part of the source code of the judge. Any modification implies that that judge must be recompiled. Here follows all possible modifications in these files, in the order where you'll meet them in the code. 3.4.1 Variant.c: Variants array In variant.c, search char *variants[]: this array contains the user names of the variants. You must add yours at the end, BEFORE the name of the variant modifiers. Don't forget the comma. 3.4.2 Variant.c: VValue array Just after that, you must define a define for the variant (used later in variant.h). Any name is permitted, though by convention it is of the form V_. 3.4.3 Variant.c: Powers array If you add any power name, add it at the end of the array powers. 3.4.4 Variant.c: Owners array If you have add any power, add the possessive form in the array owners, in the same order. Note: the sizes of both powers and owners array must match, otherwise you will get unexpected names used! 3.4.5 Variant.c: pletter array The pletter contains the abbreviations (F for France, 9 for Warsaw in a chaos...) for the powers in your variant. You must add a new line for your variant, defining which power letters will be used. The position of these power letters correspond to the position of the descriptive names in the powers and onwers arrays, defined above. Powers that are not played in this variant are represented by the 'x'. If new power(s) were added, ALL lines of all variants must be extended to have the same number of letters. 3.4.6 Variant.c: Sphase array - The sphase array contains the start season of the variant. It must be the same one as in the seed file that you have created. 3.4.7 Variant.h: Variants array In variant.h, in the first enum field, you must add a new V_ line. If you didn't count it before, this array's comments contain each variant number, that will be used as the variant number in the dip.master file. 3.4.8 Variant.h: magic numbers You may have to update these 'magic numbers' if you really have to, especially the second one if you find something more insane than a chaos (and you'll have to find yourself if lowercase letters are OK for power names...): /** UPDATE DEFINES AS NECESSARY BELOW **/ #define NVAROPTS 4 /* Number of variant options (blind/gunboat/shorthand/a/f) */ #define MAX_POWERS 36 /* Max. powers in a single game (letters+digits) */ #define LPOWER 24 /* Length of the longest power name */ 3.4.9 WILD_PLAYER If you have added new powers, you MUST increment this define accordingly by the number of powers added. The subsequent defines should be values after this (in njudge 1.4.1 onwards, this is automatic). Failure to do this will commonly result in the Master being called another name. 3.4.10 Variant.h: SETNP macro and default modifiers The macro SETNP contains the default behaviour of your variant: number of players, victory points. You must add a line for yours too. The line for the standard (7 players by default, 18 centers to win) is: case V_STANDARD: dipent.np = 7; dipent.vp = 18; break; \ Many variant modifiers can be added as the default setup of the variant. Most can be overriden at game creation by a SET commande. These many modifiers are defined in the file dip.h. Some well known are: * XF_BUILD_ANYCENTRES: a power can build on any center, like in a Chaos variant. Same as the moderator command SET ANY CENTRE[S]|CENTER[S]. * XF_BUILD_ONECENTRE: the player can build anywhere, but needs to own at least one home center, like in Classical or Aberration. * XF_COASTAL_CONVOYS: allows coastal convoys, like in Machiavelli. Same as the moderator command SET [NO] COASTAL CONVOYS. Other more or less useful modifiers are: XF_MANUALPROC, XF_NOMINORPRESS, XF_AUTODISBAND, XF_ANYDISBAND... Don't forget the \ at the end of the line. 3.4.11 starter.flist This file lists almost all files from data/. You shoul add there your info, seed, report files, as it is used as a reference for players. 4 Examples 4.1 H32 (Hundred) Wings 4.1.1 Setup (** FIXME : This part must ber updated with variant names as extensions **) H32 (Hundred Years War) with wings seems at first sight stupid, but I think the game would be changed by it. We need for this the seed_w file to place the first wings, and the report_w file to let it know to the players. We need just to copy the seed.22 and report.22 as seed_w.22 and report_w.22, and modifying them for example this way: * seed_w.22: B: A Dijon B: W Flanders B: A Luxembourg B: F Holland E: A Calais E: A Guyenne E: A Normandy E: F English Channel E: W London F: A Dauphine F: A Orleanais F: A Paris F: W Toulouse F: A Provence * report_w.22: Starting position for Spring of 1425. Burgundy:Army Dijon. Burgundy:Wing Flanders. ... France: Wing Toulouse. France: Army (unpaid and angry) Provence. Add seed_w.22 and report_w.22 to starter.flist in the source file directory. For this small variant, you don't need anything more. You can test it immediately: create ?testh32w password h32 wings set players 1 4.1.2 Test Create a new game by sending to the judge: create ?test password h32 wings set players 1 And as Burgundy, you'll be able to send your planes from Flanders directly to London. 4.2 Test variant 4.2.1 Setup (** FIXME : This part must ber updated with variant names as extensions **) This variant is called Mytest and aims to be almost the same as the standard. - See in variant.h what is the biggest variant number. It is 34 (colonial96) for my 1.3.2-pre judge, so it will be variant number 35. Create seed.35 and report.35 by copying seed.1 and report.1. Adjust this value if you have another judge with more or less variants. - Create the info.mytest file. - Add the following lines in the variants array of variant.c: "colonial96", /* Colonial 1996 Diplomacy */ "mytest", /* Test !!!! */ /** ADD NEW VARIANTS ABOVE THIS LINE! **/ - In the vvalue array: V_colonial96, /* 34 Colonial 1996 variant */ V_mytest, /* 35 Test */ /** ADD NEW VARIANTS ABOVE THIS LINE! **/ - The powers and owners don't change. - Add a line similar to the one of the standard variant to the pletter array: ".xxBxxCxxxxFxxxxxxJxxxxxxxRxxxTxxHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?xOM", /* Colonial 1996 Diplomacy */ ".AxxxxxxxExFGxxxxIxxxxxxxxRxxxTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?xOM", /* MyTest variant */ /** ADD NEW VARIANTS ABOVE THIS LINE! **/ - The start season in sphase must be the same as in the seed file: "S1870M", /* Colonial 1996 Diplomacy */ "S1901M", /* My test */ /** ADD NEW VARIANTS ABOVE THIS LINE! **/ - In variant.h, expand the enum this way: V_colonial96, /* 34 Colonial 1996 Diplomacy */ V_mytest, /* 35 my test */ /** ADD NEW VARIANTS ABOVE THIS LINE! **/ NVARIANT /* Last variant + 1 */ - In the SETNP macro, add this line (here we'll have 7 players, 10 victory points only; disband is allowad at any turn, and a retreat leads automatically to a disband): case V_mytest: dipent.np = 7; dipent.vp = 10; dipent.xflags |= XF_ANYDISBAND ; dipent.xflags |=XF_AUTODISBAND ;break; \ - It's over for the code modification. 4.2.2 Installation You should read the upgrade documentation (for example my [47]Installation guide) to avoid losing your specific configuration and some mail of you have an active judge. Basically, you have to do this: **** FIXME ***** A VALIDER !!!!!! (histoire avec num de vrsion) - The quick and dirty way is to modify directly the Makefile (change the VERSION variable from it standard version to 1.3.2+custom variants for example), and install info.mytest, seed.35 and report.35 into the data/ directory of your current running judge. - The Right Way, compulsory if you have are coming from a fresh tarball, is to : - change the version number in configure.ac (see README.hackers for details): AC_INIT("njudge", 1.3.2.020030413+variants) ; or change the Makefile after lauching - add your variant files to the starter.flist. - You must get the smail.in and defaults.inc.in from your old judge source if they are not standard. - Then compile and upgrade. On my system it means: ./configure --with-dir=/home/alex/dip --with-user=alex --with-domain=christophecourtois.org make all make upgrade 4.2.3 Test Create the game: create ?foobar password mytest set players 1 4.3 Switzerland Let's imagine that Switzerland is a territory like any other one. TODO 4.4 Chess TODO (Done already on FREE) ? 5 floc.net 6 Mapmaker DN : There are a number of files you need - a map, a report, a seed and an info file, plus you have to update the variant.h (and variant.c in the newer versions of the judge). It can be done without MapMaker. But by using MapMaker : (1) It takes a fraction of the time (2) You get Mapper, Mapit and a PS map too (3) You get floc.net support And also, you get my experience of getting a variant through draft versions without confusing the various systems that run around the judges... 7 Addmap 8 Automatic tests None known. David Norman may have some. 9 Troubleshooting These are some problems and solutions: * * 10 Integration in the official judge source CVS, Makefile.am 11 Moving variants between judges Numbers ???, 12 Misc 12.1 The author The author is 28 years old, writes SQL all day long for big corporations to eat and pay the mortgage, and is trying to learn Java, C and PHP (The most difficult part is to find some time for it...) 12.2 Thanks Many parts of this HowTo are cut-and-pasted from source code and mails of the judge-maint mailing list. 12.3 Copyright and boring stuff Permission is granted to make and distribute copies of this text provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the derived work is distributed under the terms of a permission notice identical to this one. Translations fall under the category of "modified versions". Warranty: None. Nothing. Nada. Rien. Que dalle. Nitchevo. Nichts. Do everything at your own risk. Remember this is a sum-up of a non-native English speaker on a subject he recently discovered. Redistribution is allowed and encouraged; however, it is strongly recommended that the redistributor contact the author before the redistribution, in the interest of keeping things up-to-date (you could send me a copy of the thing you're making while you're at it). Translators are also advised to contact the author before translating (no translation known for the moment). __________________________________________________________ References 1. mailto:christophe@courtois.cc 2. mailto:christophe@courtois.cc 3. mailto:christophe@courtois.cc 4. mailto:millis@faztek.org 5. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#1 6. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#1.1 7. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#1.2 8. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#1.3 9. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#2 10. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#2.1 11. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#2.3. 12. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3 13. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.1. 14. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.1.1 15. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.1.2 16. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.1.3 17. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.1.4 18. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.2 19. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.2.1 20. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.2.2 21. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.2.3 22. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.2.4 23. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.3 24. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#3.4 25. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#4 26. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#4.1 27. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#4.2 28. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#4.3 29. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#4.4 30. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#5 31. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#6 32. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#7 33. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#8 34. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#9 35. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#10 36. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#11 37. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#12 38. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#12.1 39. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#12.2 40. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#12.3 41. http://www.njudge.org/ 42. http://www.ellought.demon.co.uk/ 43. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#2.2.3 44. file://localhost/home/alex/cvs/njudge/docs/VariantsHOWTO.html#2 45. file://localhost/home/alex/cvs/njudge/docs/njudgemapdatahowto.htm 46. file://localhost/home/alex/cvs/njudge/docs/njudgemapdatahowto.htm 47. file://localhost/home/alex/cvs/njudge/docs/InstallationHOWTO.html