View source for Item Progression

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stats, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||Name||The name of the itemgroup, defined as a property on an item stat.
|-
|[[Item_Progression#LevelGroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#RootGroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#NameGroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is a property set in equipment stats, and is used to group progression settings in ItemProgressionVisuals.

To define an itemgroup, simply define the property on an equipment stat (weapon, armor, or shield):

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
</pre>

_Clubs is used as a base stat inherited by other club weapons. Here it defines "Maces_1H" as the itemgroup. If we wanted to inherit from _Clubs, but create a new itemgroup, we simply have to override the ItemGroup property:

<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

In our new stat, "WPN_Common_Mace_1H_A", we inherit from _Clubs, but override the ItemGroup with our own, thus placing progression for our new item within its own group.

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Trying to generate an item with a level range or rarity that isn't defined.'''

Say we have a weapon:

<pre>
new entry "WPN_Wikimod_Crossbow_Plus"
type "Weapon"
using "_Crossbows"
data "ItemGroup" "WPN_Wikimod_Crossbow_Plus"
data "ComboCategory" "Crossbow"
data "ObjectCategory" "Wikimod_Crossbows"
data "MinAmount" "1"
data "MaxAmount" "1"
data "Priority" "1"
data "MinLevel" "1"
</pre>

A single ItemProgressionVisuals entry:
<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Epic"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

And a TreasureTable:
<pre>
new treasuretable "ST_Wikimod_Crossbows"
new subtable "1,1"
object category "Wikimod_Crossbows",1,1,0,0,0,0,0,0
</pre>

Our table is attempting to generate our item at "Common" rarity, yet we only have an entry for the "Epic" rarity. Furthermore, attempting to generate this item at a level higher than 9 will fail. 

The solution is to add new entries for each level range and rarity we want to support (This is why the ItemProgressionVisuals in Shared contains so many entries).

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".