This readme covers the following subjects related to Contract Science Modifier mod for Kerbal Space Program:

 INSTALLATION AND UPDATE NOTES 
 SETTINGS 
 GENERAL STRUCTURE OF A CONFIGURATION FILE 
 CONFIGURATION EXAMPLES 
 DEFINING CUSTOM SETTINGS FOR STOCK CONTRACTS 
 DEFINING CUSTOM SETTINGS FOR A THIRD PARTY MOD 
 LICENSING


==== INSTALLATION AND UPDATE NOTES ====
 
If you're installing the mod for the first time, just unzip the package into your KSP\GameData folder.

Updating from a version 0.3:
* If the "factory" settings are OK for you then delete the entire mod's folder and extract a new one.
* If you have altered the mod's configuration file earlier and are happy with those settings but still want to update:
	Save the file "contract_science_modifier.cfg" somewhere or copy its entire contents to clipboard.
	Update the mod as described earlier.
	Substitute the "contract_science_modifier.cfg" with your old one.
	New version should work fine with your old config.




==== SETTINGS ====

scienceMultiplier:
	Values greater or equal to 0 affect newly offered contracts only, leaving already available or active ones untouched.
	Any value less than 0 nullifies science rewards of existing and new contracts except for already completed ones.
	Defaults to 1.
scienceCeiling:
 	Sets the ceiling that resulting science reward values should never exceed.
 	Ignored if not greater than 0.
 	Defaults to 0 (disabled).
scienceNonLinearity:
 	Sets the way of how the resulting values should respect the scienceCeiling setting. Makes sense only with positive scienceCeiling.
 	= true - makes the resulting values smoothly approach the ceiling (non-linear).
 		Consider that in order to respect the ceiling the values appear lower than expected when using this option.
 	= anything else - original reward values are simply multiplied by the scienceMultiplier (linear)
 		and everything that appears to be higher than ceiling after that is just set equal to it.
		Makes sense only with positive scienceCeiling.
 	Defaults to false.
bypass:
 	= true - makes the mod leave rewards unmodified
 	= anything else - makes the mod apply modifications on contracts' science
 	Defaults to false.

You may use either the all four, only some or none of them. Everything that is missing will be substituted with a corresponding default value.	
	


==== GENERAL STRUCTURE OF A CONFIGURATION FILE ====

The following notations will be used:
<settings> - a place where the above described settings are expected
//REQUIRED - this commentary will mark a line that's required in the configuration file. Everything else is optional.
Everything starting with < and ending with > should be replaced with appropriate values.

Here is the structure of configuration file:

CONRACT_SCIENCE_MODIFIER {					//REQUIRED. It's the root of the configuration.

	<settings>								//global settings that'll be applied for all contracts and contract parameters
	
	PARAMETER {								//a global parameter section
		type = <parameter type>				//REQUIRED if the section presents. The name of a contract parameter type e.g. Contracts.Parameters.LaunchVessel. Must always be a fully qualified name.
		<settings>							//these settings will be applied to all parameters of the specified type of all contracts
	}
	
	...										//multiple global PARAMETER sections are possible

	CONTRACT {								//section to specify settings that will affect a certain contract type
		type = <contract type>				//REQUIRED if the section presents. The name of a contract type, e.g Contracts.Templates.FirstLaunch. Must be a fully qualified name here.
		<settings>							//these settings will be applied to completion value and all parameters of the specified contract type
		
			PARAMETER {						//a contract's parameter section
				type = <parameter type>		//REQUIRED if the section presents. Same as already described above.
				<settings>					//these settings will be applied to values of the specified parameter type in contracts of the specified contract type
			}
			
			...								//multiple PARAMETER sections for a single contract type are possible
		
	}
	
	...										//multiple CONTRACT sections are possible

	NAMESPACE {								//a namespace's section. Used for defining settings for contracts generated by third party mods
		name = <namespace's name>			//REQUIRED if the section presents. The name of the namespace. The namespace is a contract's type prefix up to the last period.
											//e.g. for the contract type Contracts.Templates.FirstLaunch the namespace is Contracts.Templates
		<settings>							//these settings will be applied to completion value and all parameters of all the contract types that belong to the specified namespace
											
		PARAMETER {							//a namespace-wide parameter section
			type = <parameter type>			//REQUIRED if the section presents. Must always be a fully qualified name.
			<settings>						//these settings will be applied only to parameters of the specified type of all the contract types that belong to the specified namespace
		}
		
		...									//multiple namespace-wide PARAMETER sections are possible

		CONTRACT {							//section to specify settings that will affect a certain contract type of the specified namespace
			type = <contract type>			//REQUIRED if the section presents. The name of a contract type. When used inside a NAMESPACE section, brief contract type names are allowed,
											//e.g. FirstLaunch. If the namespace's name = Contracts.Templates is specified then it is equivalent to Contracts.Templates.FirstLaunch type name.
											//You may use either brief or a full type name here.
			<settings>						//these settings will be applied to completion value and all parameters of the specified contract type
			
				PARAMETER {					//a contract's parameter section
					type = <parameter type>	//REQUIRED if the section presents. Same as already described above.
					<settings>				//these settings will be applied to values of the specified parameter type in the contract of the specified contract type
				}
				
				...							//multiple PARAMETER sections for a single contract type are possible
			
		}
		
		...									//multiple NAMESPACE sections are possible
											
	}
	
}


It is required that contract and parameter types were specified with a fully qualified name, e. g. stock contract types must be prefixed by "Contracts.Templates."
and stock parameter types must be prefixed by "Contracts.Parameters.". The only exception is that a contract type name may be specified in a brief form if the
CONTRACT section is inside a NAMESPACE section.

The settings specified at the configuration root level (in the CONTRACT_SCIENCE_MODIFIER section) are considered as global.
As extra sections are optional you may use the same configuration file as for version 0.3.

The values of the same settings from different sections are NOT cross-multiplied in any way but OVERRIDE each other obeying the rule:
The deeper a setting is in the configuration tree the higher its priority.
The only exception is for the "bypass" setting which priority is inversed: if you set "bypass = true" in the parent then all the children will be bypassed.
Also you may omit any settings at any level. In that case settings will be searched in the parent section, up to default.

NOTE that global and namespace-wide parameter setting values may be implicitly overriden by child sections. For example, if you specify PARAMETER settings at the global
level and create a CONTRACT section with different values of the same settings then global parameter setting values will be overriden even if no PARAMETER sections
are specified for that CONTRACT. That's because of the two rules:
1. A CONTRACT section settings are applied for contract completion and for all parameters of the appropriate contract type that are not explicitly defined.
2. Resulting contract parameter setting values override any global ones.
See the below examples 4, 5.


==== CONFIGURATION EXAMPLES ====


1. Simply using the mod without any extensive configuration:

CONRACT_SCIENCE_MODIFIER {	

	scienceMultiplier = 0.07    
	scienceCeiling = 20
	scienceNonLinearity = true

}


2. Defining individual settings for a certain contract type:

CONRACT_SCIENCE_MODIFIER {	

	scienceMultiplier = 0.07    
	scienceCeiling = 20
	scienceNonLinearity = true

	CONTRACT {
	   type = Contracts.Templates.ReachSpace
	   scienceMultiplier = 2
	}

}


3. Disabling modification of science rewards for a certain mod:

CONRACT_SCIENCE_MODIFIER {	

	scienceMultiplier = 0.07    
	scienceCeiling = 20
	scienceNonLinearity = true

	NAMESPACE {
	   name = MissionControllerEC
	   bypass = true
	}

}



4. Case #1 of the above note (implicit overriding):
For demonstration purposes let's assume that AltitudeRecord parameter of ReachSpace contracts has some science reward in stock.

CONRACT_SCIENCE_MODIFIER {	

	scienceMultiplier = 0.07
   
	PARAMETER {
		type = Contracts.Parameters.AltitudeRecord
		scienceMultiplier = 0.1
	}
   
	CONTRACT {
		type = Contracts.Templates.ReachSpace
		scienceMultiplier = 0.5
	}

}

In this case the value of scienceMultiplier for entire "Reach Space" contract overrides the values specified in the global section.
Thus when a "Reach Space" contract with an "Altitude Record" parameter is offered, the multiplier 0.5 will be used, not 0.1.
To force the global value for the "Altitude Record" parameter of "Reach Space" contracts you should use the configuration similar to the next example.


5. Case #2 of the above note (forcing the globally specified value):

CONRACT_SCIENCE_MODIFIER {	

   scienceMultiplier = 0.07
   
   PARAMETER {
	type = Contracts.Parameters.AltitudeRecord
	scienceMultiplier = 0.1
   }
   
   CONTRACT {
		type = Contracts.Templates.ReachSpace
		scienceMultiplier = 0.5

		PARAMETER {
			type = Contracts.Parameters.AltitudeRecord
			scienceMultiplier = 0.1                     //Re-overriding contract's setting
		}

	}

}

In this case the scienceMultiplier of 0.5 will be used for all parameters and for contract completion of "Reach Space" contracts,
but with an exception for "Altitude Record" parameter for which the multiplier is 0.1.



==== DEFINING CUSTOM SETTINGS FOR STOCK CONTRACTS ====

For stock and FinePrint contracts there's a dummy template file named "CSM Stock and FinePrint.cfg" in the package. You only need to specify your settings there.
Stock and FinePrint have separate namespaces so you can provide different settings for them.



==== DEFINING CUSTOM SETTINGS FOR A THIRD PARTY MOD ====

There are some .cfg files in the package that contain templates for some popular mods that generate contracts. In the default state those configs
contain only namespaces and possible contract types for those mods and do nothing still letting global settings to take effect. You'll have to
provide some custom settings in the appropriate sections by yourself.

To add a config for a mod for which there's no template you'll have to look in it's source code. You need to find classes that extend Contract class.
Usually they can be found in a subfolder with the name "Contracts" or you can use a search software to find *.cs files that contain a string ": Contract"
in them. Once you find such files take a look inside. Somewhere among the first few lines you should see something like this:

...
namespace SuperContractGenerator.Stuff
{
	public class KillKenny : Contract, IMyInterface, DontKnowWhatTheHellElseMayBeHere
...

That's it. The namespace is SuperContractGenerator.Stuff and the contract type is KillKenny. So we can add a section in our config file (you can put it in any
existing .cfg file or create your own in the Contract_science_modifier's folder):

NAMESPACE {
	name = SuperContractGenerator.Stuff
	scienceMultiplier = 0.5		//Halve science rewards of all the contracts of this namespace
	
	CONTRACT {					//In case you need different settings for this type
		type = KillKenny
		scienceMultiplier = 0
	}
}

You may go on and search through the file for "AddParameter" string to determine the parameter types that are used in this contract.
Note that a mod's source file may contain several contract classes and it may define several namespaces for its contracts. Also a namespace may 
not necessarily have any similarity to the mod's or its author's names.



==== LICENSING ====

The Contract Science Modifier mod, its source code and documentation is licensed under GNU GPLv3 license. It can be found in a text file inside the mod's distributed zip-package.
Kerbal Space Program and third party mods mentioned in configuration files and in this documentation are licensed by appropriate licenses provided by their respective authors.