ReadMeSmartMap.txt
ReadMe file describing how to use SmartMap, and its various features.

Sections:
1) How to use
2) Options
3) Thanks
4) Version History


1) How to use
	Extract the SmartMap.py to your CivIv install directory's PublicMaps
	folder.  Start the game, and select Single Player followed by Custom Game.
	On the option titled 'Map:' select SmartMap as the map.  Set other options
	to your liking (I suggest trying all the defaults first!), and Launch!

	A common error is to extract to civdir\PublicMaps\SmartMap\SmartMap.py.  You 
	want to just have civdir\PublicMaps\SmartMap.py

	Be patient.  This script is slower than many of the default scripts.  A large
	map takes about 30 seconds to generate on my 1.8ghz pentium-M laptop.  Huge
	takes close to a minute.  Pangea is the slowest to generate, picking fair
	start locations takes a lot longer.


2) Options
	Options are the point of SmartMap.  There are a bunch of them.  I will 
	describe how to use each of them in turn to get just the map you are 
	looking for.

	Map: SmartMap, otherwise you're not using SmartMap!

	Size: Duel, Tiny, Small, Standard, Large, Huge.  SmartMap will use this 
	setting to determine the overall area of the map, unless you choose to override
	the width and height manually, as explained later.  SmartMap picks a random
	width and height that produce the required area, so not all maps will be the
	same shape (if you want to force a specific shape, use the overrides 
	described later).

	Climate: Temperate, Tropical, Arid, Rocky, Cold.  These mean approximately
	what they do in the normal map scripts.  Tropical has less desert and jungle than
	you would get in the normal generator.  If you feel like you get too much tundra
	and snow in temperate, try tropical.  Arid produces a lot of desert.  Rocky means
	an extra boost to hills and mountains.  Cold means more snow and tundra.

	Sealevel: low, medium, high.  This option is used by SmartMap in a unique way.  
	Since SmartMap offers a direct ocean control, sealevel is used to control inter
	continental strategy.  In particular:
		Low = all land on the map MIGHT be reachable by galley
		Medium = it is very unlikely you will be able to reach another continent by galley,
			but contact between civs on different continents may happen early due to 
			influence borders touching (it is only possible to reach another continent
			occasionally by galley due to a bug in civiv that will rarely allow a galley
			to enter an ocean tile).
		High = guaranteed that you cannot reach another continent by galley, and civ contact
			between different continents will not happen until two near as possible cities
			both reach level 3 culture, or caravel (almost always caravel happens first).
	This option is not guaranteed to be enforced if you select a non-default land style, as 
	explained later.

	Era / Speed: These options are not affect by and do not affect SmartMap

	Continents: Controls the number of continents generated by the script.  Each option is fairly
	self explanatory.  On low sea level, continents are permitted to merge, so you may receive less
	than the expected number of continents.  You may also receive less than the expected number if 
	the script cannot find enough room (as might happen if you select duel size with 36 continents).
	You may receive more than the expected number if you select a non-default land style, as explained
	later.

	Ocean: determines the percentage of ocean to be used on the map.  Note that selecting low ocean
	levels may result in a map with significantly more useful land area than is typically expected for
	a given size of map, and may cause a gameplay imbalance.

	Hills: allows you to specify what percentage of the land area should be coverd in hills.

	Peaks: allows you to specify what percentage of the land area should be coverd in peaks.

	Wrap: allows you to specify whether the map wraps around the border in x and/or y.  X wrapping is
	the standard circumnavigatable globe you probably expect, but the other options may provide for
	an entertainingly different gameplay experience.

	Terrain: selects a terrain generator.  The terrain generator decides if a given land or hill plot is
	a desert, plains, grass, tundra, or snow.  The oasis and great plains generators are taken from those
	scripts, while standard is just what you normally get on default scripts.  SmartMap is a custom terrain
	generator that knows how to generate terrain for all kinds of map setups.  I recommend SmartMap.

	Forest/Jungle: allows you to specify if you'd like more or less than the standard amount of forest and
	jungle.  Note that this option only affects the results of the SmartMap feature generator.

	Features: selects a feature generator.  Features are things like oasis, flood plains, forest, and jungle.
	They go on top of the base terrain to enhance it in some way.  Again, the oasis and great plains options
	are just what you'd expect from those scripts.  Note that you do NOT have to match terrain and feature
	generators.  Oasis terrain with Great Plains features works just fine, as do all other combinations.
	The default SmartMap feature generator generates a few combinations that do not occur in the standard
	scripts, in particular things like floodplains on grass are possible, and oasis will occassionally be seen
	on tundra.  These are things that happen on earth, and so are 'realistic' but some may find undesireable
	because they aren't normal in the sense of the default scripts.  If you are one of these people, there is
	the SmartMap Strict option, which to the best of my knowledge will not generate any combinations not found
	in the default scripts.  I recommend either SmartMap or SmartMap strict.

	Bonuses: selects how bonuses are placed.  You can choose from the standard placement or SmartMap placement.
	SmartMap attempts to be fairer about how resources are placed strategically.  I recommend SmartMap.  This 
	option also controls the placement of goody huts.  SmartMap goody huts aren't much different from standard.

	Start Placement: selects how player start positions are determined.  The SmartMap option attempts to do a
	fairer job of placing players based on an analysis of the positions of strategic resources, and is also
	more likely to place your initial settler on a tile with one tile of ocean access so that your capital can
	build ocean buildings.

	Override width/height options: these options allow you to force SmartMap to generate a specific size of map
	to your liking.  This can allow you to generate absolutely huge maps beyond the size that your computer
	memory can hold, so be careful with this.  The sizes are multiplied by 4 in each direction to determine
	the final number of plots, so a 64x32 map is really 256 tiles wide and 128 tiles tall.  A SmartMap 'huge'
	map is 16,000 tiles total area, so the 64x32 map described = 256x128 tiles = 32,768 tiles would be more
	than twice the size of SmartMap's huge, which is in turn nearly twice as big as a default map's huge.  Note
	that this allows you to play a very big map on duel, which would be a wierd experience, as many of the pacing
	elements of the game assume that you only have a certain amount of landmass to work with.

	Land Style: this option controls a couple of special features that are more dangerous to use than the others,
	and so are reserved for last.  First, you can control how round your continents will turn out.  Rounder
	continents have a tendency to be more fair, so very round is the default.  As you transition to somewhat or
	least round, you will get odder continent shapes which various people have requested, or find to be 
	'more realistic'.  Independently, you may also choose a level of fragments.  Fragments are little pieces
	of land added randomly to the map which will appear as archipelagos or odd continent outgrowths, or tiny
	islands.  You can get all sorts of interesting growth patterns with these.  However, since they may be
	placed anywhere, they may violate the sea level guarantees of separation.  They may completely join
	continents, or make them reachable by galley.  Nevertheless, some people wanted this as another way to
	have more varied or realistic maps.  The default for this option is very round, no fragments, which provides
	the most guarantees of fair gameplay, particularly for multiplayer games.  For single player games, you
	may have fun seeing what interesting other types of maps you can get with this option.

	
3) Thanks
	I'd like to thank the following people for their contributions:
	Sirian : for answering a number of questions about how map scripts work
	A Silly Goose @ CivFanatics : for early feedback
	lordroy @ CivFanatics : for lots of feedback and screenshots
	Victorvanwavere : suggestion to have a forest/jungle setting & what became land style
	Randle @ CivFanatics : report of getting capital on wrap border
	Silver14 @ Apolyton : report of too many very tall maps when x-wrapping and other early feedback
	alms66 @ Apolyton : also suggested the forest/jungle setting, and other early feedback
	Commander Bello @ Apolyton : manual width/height override and other feedback
	skodkim @ Apolyton : assorted feedback
	battists @ Apolyton : idea for this readme!


4) Version History
# Version History
# 7.0
#     Add new generation option: Land Style.  Land style allows you to opt
#       for less roundish continents, and also to allow for small independent
#       land fragments separate from the main continents.  When land fragments
#       are generated, they may be generated anywhere, and may violate the 
#       sea level strategy guarantees, so use at your own risk.  The less rounded
#       continent options without land fragments will obey the sea level rules,
#       but may be less fair.
#     Based on a report of it being annoying to have your capital placed on
#       the wrap-edge of the minimap, I now rotate the initial land placement
#       to put the minimum number possible of land near the map wrap edge.
#       While this does not guarantee this will not happen, it makes it highly
#       unlikely.
#     Further, made the first player always pick the center most start position
#       if wrap is enabled.  This should make single player games always have
#       the human player start fairly well centered.  This should absolutely
#       guarantee that a single human player will not start with their capital
#       on a map wrap edge.
#     Fixed a couple of places where I did not consider y-wrapping correctly.
#       But I guess no one plays y-wrap (or both wrap), or they'd have surely noticed.
#     Introduce option 'SmartMap Strict' for feature generation.  This will only place
#       floodplains & tundra where the normal scripts would.
#     Made floodplains on anything other than desert less likely, and oasis on tundra
#       less likely for the non-strict feature generator.
#     Enhanced the plot wetness calculator so plot wetness can be factored into more
#       of the generation process.
#     Improved the player placement rules to prefer not to place players initially
#       on a stretch of land reaching into the ocean.
#     Added ReadMeSmartMap.txt
# 6.1
#     Tweak up number of hills for 'many hills'.
# 6.0
#     Improved lake generation system, grows more lakes beyond one plot
#     Numerous terrain relevance improvements.  More desert&snow at high altitudes,
#       less desert near water, etc.
#     Changed continent computation to more accurately determine the large
#       continents, which should as a side effect improve the fair resource
#       distribution.  Removed tiny continents which will never be player
#       starts from the fair resource distribution.
#     Improved tile wetness calculator to consider number of rivers and lakes
#       touched by tile (a tile touched by fresh water on multiple sides is
#       now more likely to shift from desert->plains->grass).
#     Added a river originating at the highest point of each continent, which
#       greatly improves the fairness of river distribution overall
#     Changed forest/jungle options to allow independent choice of forest and
#       jungle coverage (light,normal,heavy independently selectable for each)
#     General code cleanup, reorganization, commenting
#     Ran code through pychecker and cleaned all warnings, pychecker found a
#       couple of legitimate bugs that may have improved the resulting maps.
# 5.1
#     Improvements to fair bonus distribution algorithm.
#     Fixed a typo bug causing python error on undefined edgeprob
#     Tweak desert rate down slightly
# 5.0
#     Work on refining the continent boundaries so water straights are not so
#       obvious when you see the resulting cymap.
#     Rewrite river generation, move it before terrain generation so terrains
#       can consider rivers (allow grasslands and other 'wetter' terrain to be
#       more common around rivers, as well as forests/jungle)
#     Replace the standard river altitude function with one that seems to yeild
#       better river paths
#     Assorted terrain and feature improvements.  Restored possibility of flood
#       plains in desert, and made terrain tend to blob together more rather
#       than appearing so completely random.  Allowed hills to have terrain rather
#       than always defaulting to grass (so desert/hills are now possible).  I can't
#       believe no one complained about that one.
#     Found a major logic error in the player placement algorithm that was unfairly
#       favoring near-lake placements (I has assumed CyPlot.isCoastalLand() was equivalent
#       to asking: can I build a lighthouse?, this turned out not to be true).
#       As a result, initial placement is much more likely to be coastal now, and 
#       this has a nice side effect of improving the average separation of players.
#     Tweaked resource rates a little more based on various feedback.
#     Replace standard lake addition function so we don't get lakes in odd places
#     Futher performance optimization.  The low and medium sea level options are
#       now more than twice as fast, and the high sea level option is about 50%
#       faster.  I can now generate a huge map with low sea level in under a minute.
#     After discovering that the map sizes in great plains are way off, resized my 
#       maps to the following settings:
#                   Duel Tiny Small Standard Large Huge
#         SmartMap: 60   100  180   320      560   1000
#         Standard: 60   104  160   273      416   640
#       This is a bump up for everything except huge, which becomes slightly smaller,
#       and thus hopefully usable by more people.
#     Added related option to override the map width and height.  You can now select
#       your map size fairly precisely, including the ability to pick map sizes that
#       are so large they may cause civiv to have problems.  Up to 256x256 map positions,
#       which would be a 1024x1024 map, with an area of over 1 million (compare to huge at
#       an area of 16 thousand!)  If you are able to generate a map of even 128x128 I'll be
#       shocked.  Nevertheless, the option is there.  So no complaining that I made huge
#       smaller!  Just set your game to huge, then override the size to whatever you want.
#       Or for a bizarre experience, set your map to duel, and override the size to whatever
#       you'd like.  For kicks I generated a 256x8 map, and that was just barely startable
#       with my 1 Gig of memory.  Minimap looks ridiculous.
# 4.2
#     Increase goody hut count slightly, particularly on maps with lots of land
# 4.1
#     Slightly refined smartmap resource placement to make distribution
#       fairer between continents, and not to allow so many duped resources
#       within one city radius
#     Small upward tweak to resource rates
# 4.0
#     Overall performance improvement:
#        Now down to about: 
#        <5 seconds for duel,tiny,small
#        10 seconds for standard,
#        40 seconds for large,
#        ~2 minutes on huge
#        On a 1.8Ghz Pentium-M with 1Gig
#     Optimize land placement speed by remembering all potential growth positions
#       rather than looking for them randomly.
#     Optimized and improved player placement function.  No longer makes certain
#       rare placement errors, and the speed is dramatically better, particularly
#       for continents with a large number of players to be placed (pangea).
#     Optimized bonus placement.  This used to get very slow on large/huge maps due
#       to making a pass through all tiles for each bonus type.  Now makes one pass
#       through all tiles and caches the result.
#     Changed the player option read function to take a string rather than an index
#       to make it clearer in code, and also make it impossible to break when
#       changing the order of options in the list.
#     Land areas are 20,40,90,210,500,1200 (duel,tiny,small,standard,large,huge)
#       Compared to  15,24,48,88 ,154,252 for great plains.
#       Smartmap rounds down calculated width and height,
#       so the areas are not quite as big as they seem,
#       but large and huge are noticeably bigger.  This allows for more flexible
#       use of the ocean coverage option.  Note to firaxis: it would be a better
#       design if in the expansion pack or a patch you passed the expected land
#       area to the grid size function from the current mod!  Then maps could
#       dynamically size themselves to the expected land area and provide fair
#       gameplay regardless of other chosen settings (and be compatible with mods
#       that make use of different sized maps ... no more hardcoding like in
#       great plains)!
#       Note: I can just barely start a huge game with 1Gig memory.  This implies
#       firaxis is using somewhere in the neighborhood of 32k memory per tile.
#       Good grief, what on earth are they storing!
# 3.2
#     Add options for specifying weight of initial jungle/forest cover
#     More performance optimizations
# 3.1 
#     Fix rare issue with placements landing too close together
#     Slight tweaks to placement scoring to value early resources higher
#     Fix issue with placements on separate continents too close together
# 3.0 
#     Re-enable climate selection, which may or may not be honored
#     Restore 36-continent option, accidental deletion
#     Create a better default option for each selector
#     Un-smooth edges near poles
#     Properly handle allowing continents to wrap on wrap axis
#     Performance optimizations by reducing function call counts
#     Custom player placement rules
#     Complete replacement of bonus system
#     Separate out goody hut placement and put in correct order
#     Cleaner debug print messages
# 2.0 
#     Reduce bonus percentage for SmartMap bonus
#     Allow standard bonus distribution as an option
#     Bias width,height towards wrap direction
#     un-straight-edge where continents meet
#     SmartMap terrainGen allows more desert
#     SmartMap featureGen suggests more forest and jungle
#     Support for random ranges in number of continents
# 1.0 
#     Initial version
