fRO_french_translation_rAthena/doc/item_group.txt

//===== rAthena Documentation ================================
//= Item Database
//===== By: ==================================================
//= rAthena Dev Team
//===== Last Updated: ========================================
//= 20210624
//===== Description: =========================================
//= Explanation of the item_group.yml file and structure.
//============================================================

Items within an item group can be retrieved through the 'groupranditem',
'getrandgroupitem', and 'getgroupitem' script commands.
The table below explains which fields are accessed in each.

+===============+=================+====================+================+
| Field         | 'groupranditem' | 'getrandgroupitem' | 'getgroupitem' |
+===============+=================+====================+================+
| GroupID       |       YES       |        YES         |      YES       |
+===============+=================+====================+================+
| Item          |       YES       |        YES         |      YES       |
+===============+=================+====================+================+
| Rate          |       YES       |        YES         |      YES       |
+===============+=================+====================+================+
| Amount        |       no        |     OPTIONAL       |      YES       |
+===============+=================+====================+================+
| SubGroup      |    OPTIONAL     |     OPTIONAL       |      YES       |
+===============+=================+====================+================+
| Announced     |       no        |        no          |      YES       |
+===============+=================+====================+================+
| Duration      |       no        |        no          |      YES       |
+===============+=================+====================+================+
| UniqueId      |       no        |        no          |      YES       |
+===============+=================+====================+================+
| Bound         |       no        |        no          |      YES       |
+===============+=================+====================+================+
| Named         |       no        |        no          |      YES       |
+===============+=================+====================+================+

---------------------------------------

GroupID: See the "Item Group ID" section in 'src/map/itemdb.hpp' and the "item groups" section in 'src/map/script_constants.hpp'.
         Supports IG_* constants. 'IG_' is appended to the name when the file is read.

---------------------------------------

Index: Unique number that can be used to add the same Item with different data in the list.

---------------------------------------

Item: Available item that will be obtained from this item group.
      Requires the AegisName of the item.

---------------------------------------

Rate: Probability to get the item. Not a percentage value!

Examples:
  - Group: MyItemGroup
    SubGroups:
      - SubGroup: 1
        List:
          - Index: 0
            Item: Knife
            Rate: 5
          - Index: 1
            Item: Dagger
            Rate: 1

	- Knife has chance 5/6 (83.3%) to be obtained
	- Dagger has chance 1/6 (16.7%) to be obtained

---------------------------------------

Amount: Amount of item that will be obtained.

---------------------------------------

SubGroup: Unique number to create a list of item.

---------------------------------------

Algorithm: Type of algorithm associated with SubGroup.

Random            - A random item is picked from the sub group using rate as chance for an item being picked.
                    The chance remains the same every time.
All               - All items in this sub group shall be picked.
                    If you use a command that is supposed to return only one item with such a sub group, then a random item is returned instead, with each
                    item having the same chance to be picked.
                    When using this algorithm, the rate must remain unspecified (0).
SharedPool        - Rate is the amount of items of this item ID in the sub group. A random item is picked from all the items in the group and then removed
                    from the sub group. That means each time an item is returned from the sub group, it will have a lower chance to be returned again and if
                    no more items of this item ID remain in the sub group, it cannot be returned at all anymore. This also means that if the server requests
                    an item from this sub group as often as there are total items in this sub group, it will get exactly the amounts specified under "rate".
                    Only when the group is completely empty or the server restarts, the group refills.

Default: SharedPool

Example:
	Item Group:
      - Group: MyItemGroup
        SubGroups:
          - SubGroup: 0
            Algorithm: All
            List:
              - Index: 0
                Item: Knife       # "must" item(s)
              - Index: 1
                Item: Dagger      # "must" item(s)
          - SubGroup: 1
            Algorithm: Random
            List:
              - Index: 0
                Item: Stiletto    # random at SubGroup 1
                Rate: 5
              - Index: 1
                Item: Stiletto_   # random at SubGroup 1
                Rate: 2
          - SubGroup: 2
            Algorithm: Random
            List:
              - Index: 0
                Item: Stiletto    # random at SubGroup 2
                Rate: 5
              - Index: 1
                Item: Dagger_     # random at SubGroup 2
                Rate: 4

	Usages:
	getgroupitem(<group_id>)
	------------
	-> 'getgroupitem(IG_MyItemGroup);'
		- Player always gets 1x Knife and 1x Dagger
		- Player has chance to get 1x Stiletto by chance 5/7 from SubGroup 1
		- Player has chance to get 1x Stiletto_ by chance 2/7 from SubGroup 1
		- Player has chance to get 1x Stiletto by chance 5/9 from SubGroup 2
		- Player has chance to get 1x Dagger_ by chance 4/9 from SubGroup 2

	getrandgroupitem(<group_id>{,<quantity>{,<sub_group>}})
	------------
	-> 'getrandgroupitem(IG_MyItemGroup);'
		- Random SubGroup: 1, Amount: [Based on list]
		- Equals to: getrandgroupitem(IG_MyItemGroup,0) and getrandgroupitem(IG_MyItemGroup,0,1)
		- Player has chance to get 1x Stiletto by chance 5/7 from SubGroup 1
		- Player has chance to get 1x Stiletto_ by chance 2/7 from SubGroup 1
		- 'must' and 'SubGroup 2' are ignored

	-> 'getrandgroupitem(IG_MyItemGroup,1);'
		- Random SubGroup: 1, Amount: 2, ignore 'amount' on the list
		- Equals to: getrandgroupitem(IG_MyItemGroup,1,1)
		- Player has chance to get 2x Stiletto by chance 5/7 from SubGroup 1
		- Player has chance to get 2x Stiletto_ by chance 2/7 from SubGroup 1
		- 'must' and 'SubGroup 2' are ignored

	-> 'getrandgroupitem(IG_MyItemGroup,3, 0);'
		- Random SubGroup: 'must', Amount: 2, ignore 'amount' on the list
		- Player has chance to get 3x Knife by chance 1/2 from 'must' SubGroup
		- Player has chance to get 3x Dagger by chance 1/2 from 'must' SubGroup
		- 'SubGroup 1' and 'SubGroup 2' are ignored

	groupranditem(<group id>{,<sub_group>})
	------------
	This command only returns an Item ID from random SubGroup. Combine with 'getitem'
	to retrieve the items.
	-> 'groupranditem(IG_MyItemGroup);'
		- Random SubGroup: 1
		- Returns Item ID of Stiletto by chance 5/7 from SubGroup 1
		- Returns Item ID of Stiletto_ by chance 2/7 from SubGroup 1
		- 'must' and 'SubGroup 2' are ignored
	-> 'groupranditem(IG_MyItemGroup,0);'
		- Random SubGroup: 0
		- Returns Item ID of Knife by chance 5/7 from 'must' SubGroup
		- Returns Item ID of Dagger by chance 2/7 from 'must' SubGroup
		- 'SubGroup 1' and 'SubGroup 2' are ignored

Example #2:

	Item Group:
	  - Group: MyItemGroup2
	    SubGroups:
	      - SubGroup: 1
	        Algorithm: SharedPool
	        List:
	          - Index: 0
	            Item: Milk
	            Rate: 10
	            Amount: 3
	          - Index: 1
	            Item: Well_Baked_Cookie
	            Rate: 5
	            Amount: 2
	          - Index: 2
	            Item: Gift_Box
	            Rate: 1

(Note: Specifying the "SharedPool" algorithm is optional, as it defaults to SharedPool if not specified.)

You can interpret this as within MyItemGroup2 there are 10 packs of 3x Milk, 5 packs of 2x Well_Baked_Cookie and 1 Gift_Box; 16 packs in total.

Usages:
'getgroupitem(IG_MyItemGroup2);'
'getrandgroupitem(IG_MyItemGroup2);'

The first time one of the two commands above are called:
	- Player has chance to get 3x Milk by chance 10/16
	- Player has chance to get 2x Well_Baked_Cookie by chance 5/16
	- Player has chance to get 1x Gift_Box by chance 1/16

Let's say a pack of Well_Baked_Cookie was received from the group. That means only 4 packs of Well_Baked_Cookie remain in the group.

The second time one of the two commands above are called:
	- Player has chance to get 3x Milk by chance 10/15
	- Player has chance to get 2x Well_Baked_Cookie by chance 4/15
	- Player has chance to get 1x Gift_Box by chance 1/15

Now a Gift_Box is received from the group. That means no more Gift_Box are remaining in the group.

The third time one of the two commands above are called:
	- Player has chance to get 3x Milk by chance 10/14
	- Player has chance to get 2x Well_Baked_Cookie by chance 4/14

After the two commands were called 16 times, the server will always have given out exactly:
	- 30 Milk (10 packs of 3x Milk)
	- 10 Well_Baked_Cookie (5 packs of 2x Well_Baked_Cookie)
	- 1 Gift_Box

Now the group is refilled and the next time the command is called, it will behave similar to the first time.

---------------------------------------

Announced: If player obtained this item, it will be broadcast to the server.
           "[Player] has won [Item] from 'Box'"

---------------------------------------

Duration: Makes the item a rental item, which will be expire in the given amount
          of minutes. Not intended for use with stackable items.

---------------------------------------

UniqueId: Makes the given item(s) with Unique ID. Item will be stacked ONLY each group
      when it obtained. Cannot be stacked with same item, even it's stackable item.
	  Example, there is Box (just call it Apple_Box) that contains 3x Apples with
	  UniqueId = 1. When Apples appear it will stack for each 3 even another 3x Apples
	  are appeared by same box. So it will be filled in inventory as:
	        3x Apples | 3x Apples | so on... | nx Apples (normal)

---------------------------------------

Bound: Binds the obtained item.
       See 'getitembound' in 'doc/script_commands.txt' for valid bound types.

---------------------------------------

Named: Inscribes the item with the obtainer's name.

---------------------------------------