documented new pack system.

git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@1343 0fc631ac-6414-0410-93d0-97cfa31319b6

doc/type/game.txt

@@ -36,8 +36,6 @@ Such a package contains a [[file:format|data file]] called <tt>game</tt> that ha
 | @statistics dimensions@	[[type:list]] of [[type:statistics dimension]]s		from fields	Dimensions for statistics, a dimension is roughly the same as an axis. <br/>By default all card fields with 'show statistics' set to true are used.
 | @statistics categories@	[[type:list]] of [[type:statistics category]]s		from dimensions	DOC_MSE_VERSION: not used since 0.3.6
 				 					 		Choices shown on the statistics panel. <br/>By default all statistics dimensions are used.
-| @pack items@			[[type:list]] of [[type:pack item]]s	 		DOC_MSE_VERSION: since 0.3.7
-				 					 		The categories of items that can be in booster packs.<br/> For example "commons", "uncommons" and "rares" are pack items.
 | @pack types@			[[type:list]] of [[type:pack type]]s	 		DOC_MSE_VERSION: since 0.3.7
 				 					 		The types of card packs that will be listed on the random booster panel.
 | @has keywords@		[[type:boolean]]			@false@		Does this game use keywords? Should the keywords tab be available?

doc/type/pack_item.txt

@@ -1,21 +1,25 @@
 Data type: card pack item
 
-DOC_MSE_VERSION: since 0.3.7
+DOC_MSE_VERSION: since 0.3.8
 
 --Overview--
 
-A type of card that can be included in [[type:pack type|card pack types]].
+A reference to another [[type:pack type]], from which one or more cards are chosen.
-
-The pack item describes how this type of card is selected from the set.
 
 --Properties--
-! Property	Type			Description
+! Property	Type				Default		Description
-| @name@	[[type:string]]		Name of this type of item.
+| @name@	Name of a [[type:pack item]]	''required''	Name of the pack item to include in this pack.
-| @filter@	[[type:script]]		Condition that a card must satisfy to be selected.
+| @amount@	[[type:scriptable]] [[type:int]]	1	How many of those cards are in the pack?
+| @weight@	[[type:scriptable]] [[type:double]]	1	How 'important' is this item?
+		 					 	Items with a higher weight will be chosen more often.
+		 					 	Cards from @filter@ will have a weight of 1.
 
---Example--
+--Examples--
->pack item:
+>item:
->	name: rare
+>	name: common
->	filter: card.rarity == "rare"
+>	amount: 11
 
-Rare cards are those with the rarity value of @"rare"@.
+Include 11 commons in this [[type:pack type|pack]].
+
+>item: common
+Short form. Include a single common in this pack.

doc/type/pack_item_reference.txt

@@ -1,24 +0,0 @@
-Data type: card pack item reference
-
-DOC_MSE_VERSION: since 0.3.7
-
---Overview--
-
-A reference to a [[type:pack item]].
-
-
-
---Properties--
-! Property	Type				Default		Description
-| @name@	Name of a [[type:pack item]]	''required''	Name of the pack item to include in this pack.
-| @amount@	[[type:scriptable]] [[type:double]]	1	How many of those cards are in the pack?
-| @type@	@"replace"@, @"no replace"@ or @"cyclic"@	@"no replace"@	How should the cards be selected? The options are: <ul><li>Random with replacement</li><li>Random without replacement</li><li>Cyclic, selecting each card in turn</li></ul>
-
---Example--
->item:
->	name: common
->	amount: 11
->	type: no replace
-
-Include 11 commons in this [[type:pack type|pack]].
-The cards will be selected without replacement, so the pack is guaranteed not to contain duplicate cards (if the set is large enough).

doc/type/pack_type.txt

@@ -1,22 +1,77 @@
 Data type: card pack type
 
-DOC_MSE_VERSION: since 0.3.7
+DOC_MSE_VERSION: since 0.3.8
 
 --Overview--
 
 A type of card packs. For instance "booster" and "tournament pack" are card pack types.
 
-A pack type contains one or more [[type:pack item reference]]s, indicating what kinds and how many cards are in the pack.
+A pack type contains either:
+* a filter for selecting the desired kind of cards from the set.
+* one or more [[type:pack item]]s, indicating what kinds and how many cards are in the pack.
+* a combination of the above.
 
 --Properties--
 ! Property	Type					Default		Description
 | @name@	[[type:string]]				 		Name of this card pack type.
+		 					 		Other pack types can refer to this name.
+| @select@	see below				see below	How are instances of this pack generated?
 | @enabled@	[[type:scriptable]] [[type:boolean]]	@true@		Is this pack type enabled, i.e. can the user select it?
-| @items@	[[type:list]] of [[type:pack item reference]]s	 	The items to include in this pack.
+| @selectable@	[[type:boolean]]			@true@		Is this pack selectable from the list of packs in the user interface?
+| @summary@	[[type:boolean]]			@true@		Is a summary of the total number of cards shown in the second panel in the user interface?<br/>
+		 					 		Note: this only applies to pack types that have the @filter@ property set.
+| @filter@	[[type:script]]				''optional''	Condition that a card must satisfy to be included in this pack type.
+| @items@	[[type:list]] of [[type:pack item]]s	 		The items to include in this pack.
+
+--Selection--
+
+The @select@ property specifies how instances of this pack are generated.
+When the user selects that he wants 3 copies of pack X, then MSE will generate three ''instances'' of that pack.
+How that happens depends on the @select@ property:
+
+! @select@		Description
+| @all@			Each instance of this pack type contains all of the filtered cards and @items@.<br/>
+			In general, @select: all@ is used for the selectable pack types, while other @select@ types are used for the rest of the packs.<br/>
+			This is the default for pack types with @items@.
+| @replace@		Each instance of this pack type contains a single card or @item@, chosen at random with replacement.
+			The probability of picking an item is proportional to its @weight@, all filtered cards have weight 1.
+| @no replace@		Each instance of this pack type contains a single card or @item@, chosen at random without replacement.
+			This means that the same card or item will not be chosen twice (if the set is large enough).<br/>
+			This is the default for pack types with a @filter@.
+| @proportional@	Each instance of this pack type contains a single filtered card or @item@, chosen with probability proportional to the number of choices for the card/item.
+			The choice is made with replacement.
+| @nonempty@		Each instance of this pack type contains a single filtered card or @item@,
+			but items that contain no cards will be ignored.
+			The choice is made with replacement.
+| @equal@		Instead of choosing cards and items at random, they are chosen to make their numbers as equal as possible.
+| @equal proportional@	A combination of @equal@ and @proportional@.
+| @equal nonempty@	A combination of @equal@ and @nonempty@.
+| @first@		If there are any cards, the first is always chosen, otherwise the first ''nonempty'' item is used.<br/>
+			@select: first@ can be used to make a kind of if statement: "If there are any X cards then use those, otherwise use Y cards".
+
+--Examples--
+>pack item:
+>	name: rare
+>	select: no replace # this is optional, 'no replace' is the default
+>	filter: card.rarity == "rare"
+
+Rare cards are those with the rarity value of @"rare"@.
+The cards are chosen without replacement, so in a single pack the same rare will not occur twice.
+
+>pack item:
+>	name: basic land
+>	select: equal
+>	filter: card.rarity == "basic land"
+
+Basic land cards are selected in equal amounts:
+Say a set contains two basic lands: "Good Land" and "Bad Land".
+Then if 6 basic lands are selected, there will always be exactly 3 "Good Lands" and 3 "Bad Lands".
+If an odd number of basic lands are selected then the amounts will be as close as possible to being equal.
+
 
---Example--
 >pack type:
 >	name: booster pack
+>	select: all # this is optional, 'all' is the default
 >	item:
 >		name: rare
 >		amount: 1
@@ -28,3 +83,27 @@ A pack type contains one or more [[type:pack item reference]]s, indicating what
 >		amount: 11
 
 A Magic booster pack contains 1 rare, 3 uncommons and 11 commons.
+
+>pack type:
+>	name: special or else common
+>	select: first
+>	item: special
+>	item: common
+
+If there are any special cards in the set, then "special or else common" will be a special card, otherwise it will be a common.
+
+>pack type:
+>	name: rare or mythic rare
+>	select: proportional
+>	item:
+>		name: rare
+>		weight: 2
+>	item:
+>		name: mythic rare
+>		weight: 1
+
+In Magic, individual "mythic rares" are twice as rare as normal rare cards.
+Since there are also less mythic rares, this does not mean that each booster pack has a 33% percent chance of containing a mythic rare.
+Instead the probability of a mythic rare is
+@number_of_mythics / (number_of_rares * 2 + number_of_mythics)@.
+So, for example if there are 20 rares in a set and only 5 mythic rares, then one in 9 "rare or mythic rare" cards will be a mythic rare.

doc/type/set.txt

@@ -20,16 +20,18 @@ such a package contains a data file called <tt>set</tt>.
 			 			 		Packages this package depends on.
 	
 | '''Specific to sets'''		<<<	<<<	<<<
-| game		Name of a [[type:game]]			''required''	The game this set is made for.
+| @game@	Name of a [[type:game]]			''required''	The game this set is made for.
-| stylesheet	Name of a [[type:stylesheet]]		''required''	The default style for drawing cards in this set.<br/>
+| @stylesheet@	Name of a [[type:stylesheet]]		''required''	The default style for drawing cards in this set.<br/>
 		 					 		This is without the game name or extension, so @"new"@ refers to the package @"gamename-new.mse-style"@.
-| set info	[[type:indexmap]] of [[type:value]]s	 	The data for the [[prop:game:set fields]] defined in the game.
+| @set info@	[[type:indexmap]] of [[type:value]]s	 	The data for the [[prop:game:set fields]] defined in the game.
-| styling	[[type:map]] of [[type:indexmap]]s of [[type:value]]s
+| @styling@	[[type:map]] of [[type:indexmap]]s of [[type:value]]s
 		 	 				Data for the 'extra fields' of the stylesheet.<br/>
 		 	 				This is first indexed by stylesheet name, then by field name.<br/>
 		 	 				Data is given not only for the set's stylesheet but also for those of cards.
-| cards		[[type:list] of [[type:card]]s		 	The cards in the set.
+| @cards@	[[type:list] of [[type:card]]s		 	The cards in the set.
-| keywords	[[type:list] of [[type:keyword]]s	 	The custom keywords in the set.
+| @keywords@	[[type:list] of [[type:keyword]]s	 	The custom keywords in the set.
+| @pack types@	[[type:list]] of [[type:pack type]]s	 	DOC_MSE_VERSION: since 0.3.8
+		 					 	The custom card pack types in the set.
 
 --Example--