Location: PHPKode > projects > webDiplomacy > webdiplomacy/doc/variants.txt
/**
 * 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 immidiately 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.
 * 
 */
Return current item: webDiplomacy