*
 * This file is part of IndustryStabilizer, which is a GameScript for OpenTTD
 *
 * IndustryStabilizer is free software; you can redistribute it and/or modify it 
 * under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2 of the License
 *
 * IndustryStabilizer is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with IndustryStabilizer; If not, see <http://www.gnu.org/licenses/> or
 * write to the Free Software Foundation, Inc., 51 Franklin Street, 
 * Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */
 
 //////////////////////////////////////////////////////////////////////////////
 // 0: INDEX
 //////////////////////////////////////////////////////////////////////////////
 1 NOTES
 2 PREMISE
 3 QUICKSTART
 4 INCORPORATION
 5 SETTINGS
 6 TESTING
 7 LIMITATIONS
 8 VERSION
 //////////////////////////////////////////////////////////////////////////////
 // 1: NOTES
 //////////////////////////////////////////////////////////////////////////////
 
 Please read this file before playing using IndustryStabilizer. 
 It contains all documentation.
 
 This is the Release version of CB script. The version numbering will match
 the beta version number that gets released. This release requires openTTD 
 1.4.0 or nightly 26156 or newer. It may work on older nightly releases, 
 but this is not guaranteed or tested.
 
 //////////////////////////////////////////////////////////////////////////////
 // 2: PREMISE
 //////////////////////////////////////////////////////////////////////////////
 
 The premise of this script is to provide a very basic functionality for those 
 games that last very long and want to use the default industry set, which features
 map production degrading over time. It will monitor the total cargo production of the 
 map and attempt to keep it at the same level by constructing additional industry when
 the production falls below a set threshold. 
 
 It will not remove existing industry when total production increases above the baseline. 
 
 When there are multiple types of industry that can produce a single cargo, 
 this script will select a random one of these types and tries to build it.
 Note: The script will not take into account any secondary cargo production, 
 which means that it might also increase the production of this second cargo.
 
 This is because that is a hard problem to solve efficiently (travelling salesman)
 
 //////////////////////////////////////////////////////////////////////////////
 // 3: QUICKSTART 
 //////////////////////////////////////////////////////////////////////////////
 
 All you have to do to use this in its most basic form  if you use the default 
 industries is to select it from the GS menu. There are no settings that need adapting.
 
 //////////////////////////////////////////////////////////////////////////////
 // 4: INCORPORATION
 //////////////////////////////////////////////////////////////////////////////
 
 This game script is really meant to be incorporated into other scripts as well. 
 There is a library which serves this purpose, also check IndustryStablilizeLib
 or ISLib for short. 
 
 //////////////////////////////////////////////////////////////////////////////
 // 5: SETTINGS 
 //////////////////////////////////////////////////////////////////////////////
 
 Industry Rebuild speed: 
	
	The script will try to rebuild industries every 'this many' days.
	Setting this value too high may cause the script to build too slowly, 
	not keeping up with the degradation. Set this too low and the script will
	take up unneccessary amounts of instructions. The default value has been 
	observed to work very well with the standard industries on map sizes 
	around the 512-1024 range. Smaller maps can do with a higher setting, 
	bigger maps may require a lower setting.
	
Industry rebuild delta size:

	For each 'this many units' of each cargo missing, the script will try to 
	construct one industry. A value of '1000' has been observed to work very 
	well with the default industries. Try setting this value higher if your 
	industry GRF has bigger (more production) industries and vice versa.
	
	Note that the script will build a minimum of one industry per interval. 
	It will start building a second at 1,000 units difference (by default), 
	a third at 2,000, and so on.
	
Rebuild Below:
	
	What percentage must production be before starting to rebuild? 
	The default is '80', which accounts fairly well for the monthly random 
	variations present for the default industries. For example, a value of 
	'100' usually results in a slightly increased industry density. 
	
	You can also use this as a means to control the amount of industry on the 
	map by setting it above the '100' value. 

Debug level

	For test output, set the debug level above 0. Using the 'debug level' 
	you can use this script to measure the total industry production of a map.
	
 //////////////////////////////////////////////////////////////////////////////
 // 6: TESTING
 //////////////////////////////////////////////////////////////////////////////
 
Please report any bugs, crashes, test findings, or suggestions to the relevant
release topic for this script. 


 //////////////////////////////////////////////////////////////////////////////
 //  7: LIMITATIONS
 //////////////////////////////////////////////////////////////////////////////

 Due to internal integer limitations, maps with industry cargo productions for any 
 induvidual cargo above 21,474,836 units per month may behave weirdly. This value is 
 lower if the 'Rebuild below' setting is above '100'. For the maximum value of 
 '400' this is at 5,368,709 units.
 
 Big maps can have large amounts of industries. If you are having problems, 
 Try setting on the 'debug' if you try using this on a big map (1,000,000 tiles or more)
 and observe if the actual cycle length matches the rebuild speed setting. If it 
 does not, you may have to increase the amount of opcodes allocated to gamescripts
 from the default of 10,000 to a higher value per tick.
 
 This has not been tested because it's unlikely to ever come up in a normal 
game. 
 
 //////////////////////////////////////////////////////////////////////////////
 // 8: VERSION
 //////////////////////////////////////////////////////////////////////////////
	
	Version 6
	
	- The meat of the script has been remade into a library.
	- This script has proper save and load support.
	- Improved code style for readability
	
	Version 5
	
	- First version with readme.
	- Added delta size setting.
	- Updated superlib version to 36 (latest)
	- Bugfix: Fixed FIRS/ECS support by capping production at 0. 
	Some NewGRF industries use negative cargo production hacks for internal 
	data storage.
	
	Version 4
	
	- first stable version.