-
Notifications
You must be signed in to change notification settings - Fork 113
/
variants.txt
executable file
·155 lines (155 loc) · 9.42 KB
/
variants.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
/**
* Variants (for variant developers and webmasters)
* ================================================
*
* Before starting
* ---------------
* *Please understand the open-source license of webDiplomacy before creating a variant for it*!
* The deal is: You get lots of free, flexible source-code which you can change however you like,
* but *you have to share derivative works (improvements, variants, etc)*!
* If someone requests a copy of the code you are running the license means you have to send it to
* them! If that doesn't fit your project *you cannot* use webDiplomacy!
*
* Also forum.webdiplomacy.net is available if you have a variant in mind but don't understand
* something technical here; every webmaster running webDiplomacy wants good variants for their
* server, so there'll be lots of help available, don't worry if you don't understand something.
*
*
* What a variant is in webDiplomacy
* ---------------------------------
* A variant is basically Diplomacy with a different map, which means a few things need to be flexible:
* - The map image
* - Countries; names, starting unit positions, colors, supply-centers
* - Territories; names, positions, borders, supply-center status
*
* But allowing only these things to change from variant to variant has two problems:
* - A variant may be different in unexpected ways, requiring patches throughout the code, making updates difficult.
* - If a variant is just a slight modification of an existing variant lots of things need to be duplicated.
*
* The way variants work in webDiplomacy is intended to allow changes to be as wide ranging as possible,
* making it possible to change just about any aspect of how a game works, keeping all variant code and
* data in one place, and allowing small changes to existing variants.
*
*
* How to install a variant
* ------------------------
* Variants contain PHP code, and like any code you should only run it if it is from a
* trusted source. Also check that it will work with the webDiplomacy version you have installed.
*
*
* > Once checked copy the folder into your "variants/" folder.
*
* > Open the folder you just copied across and check on variant.php; the main class for any variant,
* which every variant has.
* -> You may want to change the $id value, the variant-ID number, if you have already installed a
* variant with the new variant's default ID.
* -> Also you may need to change the $mapID from the default value; this ID refers to the map this
* variant uses. When two variants use the same map (a rule-variant) it is more efficient to make
* them use the same map data, and this is done by making them share the same mapID.
* -> On the same note some variants may depend on others (usually because they share map data).
* -> Finally you should check the cache/ sub-folder, which all variants have to store frequently used
* pre-calculated data, that it can be written to by your web-server user.
*
* > Now that you know the variant-ID number, the name of the new variant, and have done the checks
* above you can go to config.php to activate the variant.
* -> Find $variants, and add the new variant to the list. The list contains the variant-names indexed
* by the ID number. So the "Classic" variant has a variant ID of 1, it is stored in the $variants
* list as 1=>'Classic'. To add a variant called "Foobar" with a variant ID of 10 it would be set to
* $variants=array(1=>'Classic',10=>'Foobar');
* -> The variant is now activated. When the code is first initialized (probably on the "New Game" page)
* it will detect that it is the first time it has run and will run the install.php file automatically,
* which will load up the board data into the database, save javascript board representations, and
* make caches for efficiency.
* This may take a while the first time it runs, especially for large maps.
*
* > The variant can now be played by the users
*
*
* What a variant looks like
* -------------------------
* variant.php = The main variant class, which handles most of the variant-specific tasks like specifying
* which classes the variant changes.
* install.php = Runs when the main variant class is loaded but detects that the variant data isn't loaded
* into the database. Usually installs map data; variants which don't use their own map can
* directly call the install.php of the variant which defined the map they use.
* cache/ = Data is stored in here which would otherwise need to be recalculated from the database
* each time the variant gets loaded. (Supply center counts, coastal->decoastal territory
* translation, etc.)
* resources/ = Static files used by the variant like images, style-sheets, javascript code.
* For variants which define their own map this will usually contain the map images. All
* variants must have a variant.css file here, which defines the country-colors the variant
* uses.
* classes/ = The code which the variant modifies, more on this later. If this was empty the variant
* would do more or less nothing; the contents of this folder sets out exactly what the
* variant changes.
*
*
* How a variant works
* -------------------
* All objects loaded for processing/displaying games/members/chatboxes/orders etc etc are done through a
* variant layer. Just about any functionality in any game-related code can be replaced or extended, without
* needing to alter the standard non-variant code in any way.
* However by default, without any direction from variant.php, all object loaded pass directly through the
* variant layer without any replacement. Even quite different variants usually only need to change a few
* small things.
*
* The standard variants which come with webDiplomacy were written to test and demo this more than anything
* else; most of them use the Classic map but alter some code in various ways.
*
* Classic itself alters standard webDip code:
* - It defines its own map, and so has to extend drawMap.php . variants/Classic/classes/drawMap.php
* contains a list of all the things that will usually need to be changed to draw a new map.
* - Also most all variants which define their own map will need to alter the pre-game adjudicator, which
* allocates which units go to which countries. This is done via variants/Classic/classes/adjudicatorPreGame.php
* - Classic uses fair country-balancing code, which aren't yet made generic for all variants, so the default
* is simple random country-balancing which works with any variant, and Classic's extended adjudicatorPreGame
* object contains the fairer country-balancer.
*
*
* The World variant shows how an alternate map can be defined, but it's fairly similar to the Classic
* variant in terms of rules etc, only the map has changed, so it works similarly to Classic. Other than
* changing Game objects to show different dates (starting in the year 2000 instead of 1901) it is like
* Classic except with different map data.
*
*
* The other variants all extend the Classic variant in different ways, in ways that show how to make
* fun changes to parts of the game while keeping within the variant's own folder. Combined with alternate
* maps the techniques let variants make lots of changes.
*
*
* FleetRome is the best example of a small variant, showing the bare basics of what is required. It is
* simply Classic except Rome starts with a fleet instead of an army.
* It doesn't define its own map, and makes no changes to it, so it doesn't need its own install.php data,
* or its own drawMap extension. It uses the same mapID as Classic, and extends the Classic variant object
* which means it immediately behaves just like Classic and only modifications need to be layered on.
*
* variants/FleetRome/classes/adjudicatorPreGame.php is the only object modified. It extends
* variants/Classic/classes/adjudicatorPreGame.php, so without any code it inherits Classic's fair-balancing
* code.
* The class simply alters the starting unit data which adjudicatorPreGame uses, making the one Army->Fleet
* change needed.
*
* The single CSS resource file, install.php, and cache directory, are bare-bones and represent the minimum
* a variant needs to run.
*
*
* Next on the difficulty scale is CustomStart. It also extends Classic, and uses the standard map. It
* changes game rules so that the first phase is unit-placing, before Spring 1901 starts.
* adjudicatorPreGame is modified so that no starting units are created. The two functions which write the
* start units to the database are replaced with nothing, removing the standard functionality without
* leaving the variants folder.
* processGame is also altered to change the way phases progress. Other than in the first turn it calls
* standard processGame code which behaves as usual, the only modifications apply to the first turn.
*
*
* Finally BuildAnywhere demos altering the OrderInterface and userOrderBuilds order validator to make
* changes to what moves are allowed. In this case build rules are changed so that players can build on
* any supply center they own.
* This also requires modifications to the client-side JavaScript, so this variant comes with a JavaScript
* resource which alters order-generation code.
*
*
* The best way to build a variant is to take an existing one and change it until it does what you need.
* The code should be commented enough to copy a variant and change it as you go.
*
*/