Merge pull request #2309 from guilherme-gm/201810-randomopt-drop

Support for monster drops with Random Options

2 files changed, 150 insertions, 15 deletions

diff --git a/doc/mob_db.txt b/doc/mob_db.txt
index 29d2ab465..d62181048 100644
--- a/doc/mob_db.txt
+++ b/doc/mob_db.txt
@@ -63,10 +63,14 @@ mob_db: (
 	MvpExp: mvp experience                (int, defaults to 0)
 	MvpDrops: {
 		AegisName: chance             (string: int)
+        // or
+		AegisName: (chance, "Option Drop Group")
 		// ...
 	}
 	Drops: {
-		AegisName: chance         (string: int)
+		AegisName: chance             (string: int)
+		// or
+		AegisName: (chance, "Option Drop Group")
 		// ...
 	}
 },
@@ -199,21 +203,55 @@ MvpExp: Base Experience given by the monster to the player who inflict more atta
 
 
 MvpDrops: Sets monster mvp drops list. Requires to have MvpExp to trigger.
-          Accepted values are AegisName as defined on item_db.conf and a chance.
+          There are two ways to define a drop:
+          1) The first one is used for simple drops and uses the item AegisName 
+          as defined on item_db.conf and a chance.
+          Format:
+               AegisName: chance
           Chance is an integer from 1 to 10000 (10000 = 100%).
-          Required format:
-          MvpDrops: {
-          	AegisName: chance
-          	// ...
-          }
-          When not specified, becomes false.
+
+          2) The second way to define a drop allows setting a random option drop
+	      group to be used by this drop.
+          Format:
+               AegisName: (chance, "Option Drop Group")
+
+          The item drop chance refers to the chance of dropping this item, same as chance in the first option.
+          the "Option Drop Group" parameter refers to an entry on option_drop_group database file. The specified
+	      entry will be used when this item is dropped in order to add random options to the dropped equipment.
+
+	      A monster drop list may use both format for different items.
+	      Required Format:
+	      Drops: {
+		      AegisName: chance
+		      // or
+		      AegisName: (chance, "Option Drop Group")
+	      }
+
+	      When not specified, becomes false (no drops).
 
 Drops: Sets monster drops list.
-       Accepted values are AegisName as defined on item_db.conf and a chance.
+       There are two ways to define a drop:
+       1) The first one is used for simple drops and uses the item AegisName 
+       as defined on item_db.conf and a chance.
+       Format:
+            AegisName: chance
        Chance is an integer from 1 to 10000 (10000 = 100%).
-       Required format:
-       Drops: {
-       	AegisName: chance
-       	// ...
-       }
-       When not specified, becomes false.
+
+       2) The second way to define a drop allows setting a random option drop
+	   group to be used by this drop.
+       Format:
+            AegisName: (chance, "Option Drop Group")
+
+       The item drop chance refers to the chance of dropping this item, same as chance in the first option.
+       the "Option Drop Group" parameter refers to an entry on option_drop_group database file. The specified
+	   entry will be used when this item is dropped in order to add random options to the dropped equipment.
+
+	   A monster drop list may use both format for different items.
+	   Required Format:
+	   Drops: {
+		   AegisName: chance
+		   // or
+		   AegisName: (chance, "Option Drop Group")
+	   }
+
+	   When not specified, becomes false (no drops).
diff --git a/doc/option_drop_group.md b/doc/option_drop_group.md
new file mode 100644
index 000000000..325cf9fe2
--- /dev/null
+++ b/doc/option_drop_group.md
@@ -0,0 +1,97 @@
+# Option Drop Group Database
+
+## Description 
+Explanation of the `db/option_drop_groups.conf` file and structure.
+
+This database file allows the creation of groups of random options
+that will be added to certain equipments when dropped. After creating
+a group in this database file, you may set up drops in `mob_db` to use
+it in order to get items with these options. For more information on
+adding option drop groups to `mob_db`, check `doc/mob_db.txt` documentation file.
+
+Each item may have up to `MAX_ITEM_OPTION` options at the same time,
+in this document, each of these independent options will be called
+`option slot`. One drop group will define the possibilities of random
+options for each of these slots.
+
+## Entries Format
+
+```
+<Group Name Constant>: (
+	{ // Option Slot 1
+		Rate: (int) chance of filling option slot 1 (100 = 1%)
+
+		// Possible options for slot 1
+		// min/max value : int, defaults to 0
+		// chance : int, 100 = 1% if not set, will be 100%/number of possibiltiies
+		OptionName: value
+		// or
+		OptionName: [min value, max value]
+		// or
+		OptionName: [min value, max value, chance]
+		// ...  (as many as you want)
+	},
+	// ... (up to MAX_ITEM_OPTION)
+),
+```
+
+### `Group Name Constant`
+This is the group name, it is how this group is referenced in other files
+(e.g. mob_db). It must be globally unique, as it is a server constant, and
+must contain only letters, numbers and " _ ".
+
+### `Rate`
+This is the chance of this option slot to drop. In other words, this is the
+chance of getting this slot filled with something, where something is given
+by the list of `OptionName` that follows.
+
+Rate is an integer value where 100 means 1%.
+
+### `OptionName`
+Adds `OptionName` as one option that may fill this slot when it drops.
+
+The details of this option may be specified in one of 3 ways:
+
+#### `OptionName: value`
+The chance of this option being picked is auto calculated (see below),
+and if this option is chosen, its value will be `value`.
+
+#### `OptionName: [min, max]`
+The chance of this option being picked is auto calculated (see below),
+and if this option is chosen, its value will be a random integer between
+`min` and `max` (both included).
+
+#### `OptionName: [min, max, chance]`
+The chance of this option being picked is `chance`, and if this option is chosen,
+its value will be a random integer between `min` and `max` (both included).
+
+#### Auto calculated chances
+When chance is not specified in an option, it will be auto calculated by
+the server as being `100%/num`, when `num` is the number of possibilities
+in this option slot.
+
+For example, if you specify 3 possible options, all of them without 
+a `chance` defined, all of them will have 33.33% chance of being
+picked (100%/3). If you set the chance of one of them to 50%, you
+will have one option with 50% chance, and each of the others with
+33.33% chance.
+
+## Example
+```
+MYITEM: (
+	{ // Option Slot 1
+		Rate: 10000 // It has 100% of chance of being filled
+
+		// This slot may have one of the following options:
+		WEAPON_ATTR_WIND: 5,                // WEAPON_ATTR_WIND Lv5 (33.33%)
+		WEAPON_ATTR_GROUND: [2, 4]          // WEAPON_ATTR_GROUND Lv 2~4 (33.33%)
+		WEAPON_ATTR_POISON: [1, 4, 8000]    // WEAPON_ATTR_POISON Lv 1~4 (80%)
+	},
+	{ // Option Slot 2
+		Rate: 5000 // It has 50% of chance of being filled
+
+		// If filled, may have one of the following options:
+		WEAPON_ATTR_WATER: 4     // WEAPON_ATTR_WATER Lv4 (100%)
+	}
+)
+```