ParameterDefs.txt

This file can be used to specify custom parameters that players can set for this scenario before starting it. Intended usages include difficulty or map size settings.

Names and descriptions can be localized the same way scripts can using $id$ strings and corresponding string table entries.

At the moment, parameters can only be set in the lobby of network games.

Any number of sections [ParameterDef]
Value	Data type	Description	Default value
Name	String	Label put in front of this parameter.
Description	String	Description for setting used as tool tip on the control.
ID	String	Identifier for this parameter. Should be a valid identifier containing only letters, numbers and underscores and should not begin with a number. The script engine prefixes this name with SCENPAR_ and uses it to register the picked value as a constant before game initialization.
Type	String	Data type of parameter. At the moment, only Enumeration is supported.	Enumeration
Default	Integer	Value of default option that is chosen if the user does not select anything.	0
LeagueValue	Integer	If nonzero, the parameter will be forced to this vlaue in league games.	0
Achievement	String	If set to an achievement ID, this parameter is hidden in the selection dialogue and only used to track player achievements for this scenario. See section below.

Each parameter of type Enumeration should be followed by subordinate section [Options], which contains several subordinate sections [Option]. Subordinate sections need to be indented further than their parent section.

Any number of sections [Option]
Value	Data type	Description	Default value
Name	String	Label used in dropdown menu for this option.
Description	String	Description for element in dropdown menu for this option. Currently not shown.
Value	Integer	Value that is assigned to the script constant if this option is picked. Each option within one parameter definition should have a unique value.	0

Achievements

Scenario achievements are special parameter definitions for which the values are stored per player and per scenario. These parameters cannot be set maually, but can only be gained in game using the GainScenarioAchievement function. Each achievement that has been gained is represented by a small image beside the scenario title in the scenario selection dialogue.

Achievements need to be defined as parameter definition with the Achievement value set in the [ParameterDef] section. The value corresponds to the icon file name formatted as Achv*.png, where * is replaced by the achievement name. The icon may either be placed in the scenario or - if multiple scenarios share the same icon - in the global Graphics.ocg file. Icons are square with the height determining the dimensions.

By using achievement values higher than one, multiple stages of an achievement may be defined e.g. for finishing a scenario on different difficulties. The achievement value denotes the 1-based index in the icon file with multiple icons arranged from left to right.

If several players are activated while the scenario selection dialogue is opened, the player with the highest achievement value is considered for each achievement.

Example

Example ParameterDef.txt file for a difficulty setting in a scenario that controls the amount of meteorites:

[ParameterDef]
Name=$Difficulty$
Description=$DescDifficulty$
ID=Difficulty
Default=15
	[Options]
		[Option]
		Name=$Easy$
		Description=$DescEasy$
		Value=15
		
		[Option]
		Name=$Hard$
		Description=$DescHard$
		Value=100

[ParameterDef]
ID=Done
Achievement=Done
	[Options]
		
		[Option]
		Description=$AchvEasy$
		Value=1
		
		[Option]
		Description=$AchvHard$
		Value=3

The names and descriptions are localized strings which can be set for English in a StringTblUS.txt:

Difficulty=Difficulty
Easy=Easy
Hard=Hard
DescDifficulty=Conrols the amount of meteorites
DescEasy=Very few meteorites
DescHard=Lots of meteorites
AchvEasy=Finished on easy.
AchvHard=Finished on hard.

Finally, the Script.c file of the scenario should contain code to evaluate the setting and give an achievement accordingly:

func Initialize()
{
	// Meteorite amount depending on difficulty setting
	Meteor->SetChance(SCENPAR_Difficulty);
}

func OnGoalsFulfilled()
{
	GainScenarioAchievement("Done", BoundBy(SCENPAR_Difficulty, 1, 3)); // 1 for easy, 3 for hard
	return false;
}

Sven2, 2014-09