Editing Module:HeroData/docGive feedback

Also see:
* [[Module:HeroData/nav]] - For nav box purposes
* [[Module:HeroData/release]] - For determining the release status of a hero
* [[Module:HeroData/name]] - For determining translation key using hero name
* [[Module:HeroDataArrays]] - For tables in stat pages

== Overview ==

This module provides functions to create hero infoboxes, statboxes, or retrieve hero information using the data uploaded to [[Data:HeroData.json]].

Both will automatically be translated depending on the language selected. If called on
* '''[[Page]] - translates to english
* '''[[Page/en]] - translates to english
* '''[[Page/es]] - translates to spanish
See [[Template:Lang]] for more

== Functions ==

=== get_hero_var ===
Retrieve a hero variable's value, such as Abram's MaxHealth

====Parameters====
* '''hero_name''' - Name of the hero in english, or key of the hero. Preferred and recommended to use hero key, as its much more efficient. Search for the key in [[Data:HeroData.json]]
* '''hero_var''' - Key of the hero's variable, see [[Data:HeroData.json]]
* '''sig_figs_or_localize''' - OPTIONAL, # of sig figs to round to if retrieving a float, or "true" if its a string that should be localized. See Localizable values section.

Note: Recommended to use hero key where possible, i.e. hero_atlas as its O(1) time complexity instead of hero name (Abrams) which is O(N).

====Examples====
From wikitext:<br>
Using hero name in english

<pre>{{#invoke:HeroData|get_hero_var|Abrams|MaxHealth}}</pre>
{{#invoke:HeroData|get_hero_var|Abrams|MaxHealth}}


Using hero key

<pre>{{#invoke:HeroData|get_hero_var|hero_atlas|MaxHealth}}</pre>
{{#invoke:HeroData|get_hero_var|hero_atlas|MaxHealth}}


<pre>{{#invoke:HeroData|get_hero_var|Abrams|FalloffStartRange}}</pre>
{{#invoke:HeroData|get_hero_var|Abrams|FalloffStartRange}}


Round to 2 sig figs

<pre>{{#invoke:HeroData|get_hero_var|Abrams|FalloffStartRange|2}}</pre>
{{#invoke:HeroData|get_hero_var|Abrams|FalloffStartRange|2}}


<pre>{{#invoke:HeroData|get_hero_var|Abrams|WeaponName}}</pre>
{{#invoke:HeroData|get_hero_var|Abrams|WeaponName}}


Localize

<pre>{{#invoke:HeroData|get_hero_var|Abrams|WeaponName|true}}</pre>
{{#invoke:HeroData|get_hero_var|Abrams|WeaponName|true}}

====Notes====
Only usable on variables that are integers, strings, or floats (meaning not dictionaries/hashes or arrays/lists).

If using sig_figs parameter, ensure the value is a float.

If using localize parameter, ensure the value is a string. See [[Data:HeroData.json]], you will notice that hero_astro's "Lore" variable has the value "hero_astro_lore". This key is then sent to [[Module:Lang]] which checks for it in [[Data:Lang_en.json]] (or a different language).

=== get_list_elem ===
Retrieve a specified element from a list

==== Parameters ====
* '''hero_name''' - Name of the hero in english, or hero key. Preferred and recommended to use hero key, as its much more efficient. Search for the key in [[Data:HeroData.json]]
* '''hero_var''' - Key of the hero's variable, see [[Data:HeroData.json]]
* '''number''' - Index to retrieve from the list. 1 for 1st element, 2 for 2nd element, etc.
* '''localize''' - OPTIONAL - "true" if its a string that should be localized. See Localizable values section.

==== Example ====
From wikitext:<br>
Using hero name in english
<pre>{{#invoke:HeroData|get_list_elem|Abrams|WeaponTypes|2}}</pre>
{{#invoke:HeroData|get_list_elem|Abrams|WeaponTypes|2}}


Using hero key
<pre>{{#invoke:HeroData|get_list_elem|hero_atlas|WeaponTypes|2}}</pre>
{{#invoke:HeroData|get_list_elem|hero_atlas|WeaponTypes|2}}


<pre>{{#invoke:HeroData|get_list_elem|Abrams|WeaponTypes|2|true}}</pre>
{{#invoke:HeroData|get_list_elem|Abrams|WeaponTypes|2|true}}


=== get_hero_scalar ===
Retrieve a hero variable's scalar value that is inside either "Spirit Scaling" or "Level Scaling", such as Abram's BulletDamage (scaling).

====Parameters====
* '''hero_key''' - Key of the hero. Search for the key of a given hero in [[Data:HeroData.json]]
* '''scaling_type''' - "Spirit" or "Level"
* '''hero_var''' - Key of the hero's variable that is inside either "Spirit Scaling" or "Level Scaling", see [[Data:HeroData.json]]
* '''sig_figs_or_localize''' - OPTIONAL, # of sig figs to round to.

====Examples====
<pre>{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage}}</pre>
{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage}}

Round to 2 sig figs
<pre>{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2}}</pre>
{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2}}

=== get_hero_key ===
Returns the key of the specified hero's english name

====Parameters====
* '''hero_name''' - Name of the hero in english

====Example====
<pre>{{#invoke:HeroData|get_hero_key|Abrams}}</pre>

=== get_ability_key ===
Gets the ability key from a hero's bound ability slot

====Parameters====
* '''hero_key''' - Key of the hero
* '''slot_number''' - Slot number (1-based index)

====Example====
<pre>{{#invoke:HeroData|get_ability_key|hero_atlas|1}}</pre>

=== get_hero_tag ===
Retrieve a hero's description tags with [[Module:Lang]], to be used in [[Template:HeroRosterCard]] and [[Template:Infobox hero]]

====Parameters====
* '''name''' - Name of the hero in english. This is normally referenced from the template parameters
* '''number''' - Which tag to call (1, 2 or 3)

====Example====
<pre>{{#invoke:HeroData|get_hero_tag|Abrams|1}}</pre>

=== write_infobox ===
Writes a [[Template:Infobox_hero]] template call for a given hero

====Parameters====
* '''hero_name''' – Name of the hero, in english

====Example====
From wikitext:<br>
<pre>{{#invoke:HeroData|write_infobox|HERO_NAME}}</pre>

Which outputs
{{#invoke:HeroData|write_infobox|Abrams}}


=== write_stat_infoboxes ===
Writes all 3 [[Template:Infobox_stat]] template calls (Weapon, Vitality, Spirit) for a given hero

====Parameters====
* '''hero_name''' – Name of the hero, in english

====Example====
From wikitext:<br>
<pre>{{#invoke:HeroData|write_stat_infoboxes|HERO_NAME}}</pre>

Which outputs
{{#invoke:HeroData|write_stat_infoboxes|Abrams}}

=== write_hero_comparison_table ===
Writes the [[Hero Comparison]] table for a specific Level and Spirit Power

====Parameters====
* '''level''' - Number of [[Level]]s / Power Increases
* '''spirit_power''' - Amount of Spirit power

Both parameters are optional, as if both are 0 or not provided, the outputted table will be at base and will also include the level/SS scaling in each cell along with the base value, rather than the scaled value.

====Example====
From wikitext:<br>
<pre>{{#invoke:HeroData|write_hero_comparison_table|LEVEL|SPIRITPOWER}}</pre>

Which outputs
{{#invoke:HeroData|write_hero_comparison_table|11|200}}

=== write_role_playstyle_quote ===
Writes a formatted role and playstyle quotation for a hero

====Parameters====
* '''hero_key''' - Key of the hero

====Example====
<pre>{{#invoke:HeroData|write_role_playstyle_quote|hero_atlas}}</pre>

=== write_default_items ===
Writes the recommended items list for a hero

====Parameters====
* '''hero_key''' - Key of the hero (unlocalized)

====Example====
<pre>{{#invoke:HeroData|write_default_items|hero_atlas}}</pre>

=== write_ground_dash_buckets ===
Outputs a wikitable of heroes grouped by their GroundDashDuration using [[Template:HeroIcon]]

====Example====

<pre>{{#invoke:HeroData|write_ground_dash_buckets}}</pre>

{{#invoke:HeroData|write_ground_dash_buckets}}

== Localizable values ==
Localizable values as of writing this:
* Hero names (via hero keys)
* Lore
* Playstyle
* Role
* WeaponDescription
* WeaponName
* elements in WeaponTypes
* elements in RecommendedItems
* All stat labels and postfixes
* Ability descriptions and names
* Hero tags (1, 2, 3)

== Internal Utility Functions ==
The following functions are primarily for internal use but may be useful for advanced users:

=== get_json_item ===
Returns the table of a specific hero by name

====Parameters====
* '''name''' - Name of the hero in english

=== get_similar_items ===
Returns an array of hero tables that have a specified property

====Parameters====
* '''property''' - Property key to search for

== Scaling System ==
The module supports two types of scaling:
* '''Spirit Scaling''' - Affects stats based on Spirit Power
* '''Level Scaling''' - Affects stats based on Power Increases/Levels/Boons
@@ Line 2: / Line 2: @@
 * [[Module:HeroData/nav]] - For nav box purposes
 * [[Module:HeroData/release]] - For determining the release status of a hero
+* [[Module:HeroData/name]] - For determining translation key using hero name
 * [[Module:HeroDataArrays]] - For tables in stat pages
@@ Line 65: / Line 66: @@
 If using localize parameter, ensure the value is a string. See [[Data:HeroData.json]], you will notice that hero_astro's "Lore" variable has the value "hero_astro_lore". This key is then sent to [[Module:Lang]] which checks for it in [[Data:Lang_en.json]] (or a different language).
-This function will automatically search for the variable in the hero's top-level data, then the 'Weapon' block, then the 'AltFire' block.
-=== get_alt_fire_var ===
-Retrieve a hero's variable's value from "AltFire" table. Works the same as get_hero_var
-====Examples====
-<pre>{{#invoke:HeroData|get_alt_fire_var|Viscous|BulletDamage}}</pre>
-{{#invoke:HeroData|get_alt_fire_var|Viscous|BulletDamage}}
 === get_list_elem ===
@@ Line 109: / Line 100: @@
 * '''hero_var''' - Key of the hero's variable that is inside either "Spirit Scaling" or "Level Scaling", see [[Data:HeroData.json]]
 * '''sig_figs_or_localize''' - OPTIONAL, # of sig figs to round to.
-* '''no_template''' - OPTIONAL, return numerical value instead of scaling template. Has to be defined as "true"
 ====Examples====
@@ Line 118: / Line 108: @@
 <pre>{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2}}</pre>
 {{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2}}
-No template
-<pre>{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2|no_template=true}}</pre>
-{{#invoke:HeroData|get_hero_scalar|hero_atlas|Level|BulletDamage|2|no_template=true}}
-====Notes====
-If the scaling type or the stat key is not found in the hero's data, this function returns an empty string instead of an error message.
-=== hero_has_stat ===
-Checks if a hero possesses a specific stat in their Base data, Level Scaling (Boons), or Spirit Scaling. Used primarily for conditionally hiding rows in infoboxes.
-The base value is looked up in the hero's top-level data, then the 'Weapon' block, then the 'AltFire' block, the same as get_hero_var. A stat counts as present when its base value is non-zero, or when it has any non-zero scaling.
-====Parameters====
-* '''hero_key''' - Key of the hero.
-* '''stat_key''' - Key of the stat to check (e.g., BulletResist, TechResist).
-====Example====
-<pre>{{#invoke:HeroData|hero_has_stat|hero_kelvin|TechResist}}</pre>
-{{#invoke:HeroData|hero_has_stat|hero_kelvin|TechResist}}
 === get_hero_key ===
-Returns the key of the specified hero's english name. A hero key may also be passed, in which case it is returned unchanged. Matching is case-insensitive. Returns "Hero not found." when the input matches no hero.
+Returns the key of the specified hero's english name
 ====Parameters====
-* '''hero_name''' - Name of the hero in english, or a hero key
+* '''hero_name''' - Name of the hero in english
 ====Example====
 <pre>{{#invoke:HeroData|get_hero_key|Abrams}}</pre>
-=== resolve_key ===
-The same lookup as get_hero_key, but returns an empty string instead of "Hero not found." when the input matches no hero. Intended for templates that need to branch on whether the input names a hero at all.
-====Parameters====
-* '''hero_name_or_key''' - Name of the hero in english, or a hero key
-====Example====
-<pre>{{#invoke:HeroData|resolve_key|Abrams}}</pre>
-{{#invoke:HeroData|resolve_key|Abrams}}
 === get_ability_key ===
@@ Line 178: / Line 138: @@
 <pre>{{#invoke:HeroData|get_hero_tag|Abrams|1}}</pre>
-=== has_tags ===
+=== write_infobox ===
-Returns "true" when the hero has description tags, or an empty string otherwise. Intended for templates that need to hide a tag block entirely for heroes without tags.
+Writes a [[Template:Infobox_hero]] template call for a given hero
 ====Parameters====
-* '''name''' - Name of the hero in english
+* '''hero_name''' – Name of the hero, in english
+====Example====
+From wikitext:<br>
+<pre>{{#invoke:HeroData|write_infobox|HERO_NAME}}</pre>
+Which outputs
+{{#invoke:HeroData|write_infobox|Abrams}}
+=== write_stat_infoboxes ===
+Writes all 3 [[Template:Infobox_stat]] template calls (Weapon, Vitality, Spirit) for a given hero
+====Parameters====
+* '''hero_name''' – Name of the hero, in english
+====Example====
+From wikitext:<br>
+<pre>{{#invoke:HeroData|write_stat_infoboxes|HERO_NAME}}</pre>
+Which outputs
+{{#invoke:HeroData|write_stat_infoboxes|Abrams}}
+=== write_hero_comparison_table ===
+Writes the [[Hero Comparison]] table for a specific Level and Spirit Power
+====Parameters====
+* '''level''' - Number of [[Level]]s / Power Increases
+* '''spirit_power''' - Amount of Spirit power
+Both parameters are optional, as if both are 0 or not provided, the outputted table will be at base and will also include the level/SS scaling in each cell along with the base value, rather than the scaled value.
 ====Example====
-<pre>{{#invoke:HeroData|has_tags|Abrams}}</pre>
+From wikitext:<br>
-{{#invoke:HeroData|has_tags|Abrams}}
+<pre>{{#invoke:HeroData|write_hero_comparison_table|LEVEL|SPIRITPOWER}}</pre>
+Which outputs
+{{#invoke:HeroData|write_hero_comparison_table|11|200}}
 === write_role_playstyle_quote ===
@@ Line 230: / Line 223: @@
 == Internal Utility Functions ==
-The following functions are called directly from Lua by other modules, not from wikitext:
+The following functions are primarily for internal use but may be useful for advanced users:
 === get_json_item ===
@@ Line 238: / Line 231: @@
 * '''name''' - Name of the hero in english
-=== get_stat ===
+=== get_similar_items ===
-Returns the value of a stat, checking the hero's top-level data, then the 'Weapon' block, then the 'AltFire' block. Returns nil when the hero has no such stat. This is the shared lookup behind get_hero_var, get_list_elem and hero_has_stat.
+Returns an array of hero tables that have a specified property
-====Parameters====
-* '''hero_data''' - Hero table, such as the one returned by get_json_item
-* '''stat''' - Key of the stat
-=== get_scalings ===
-Returns an ordered list of a hero's scalings for a stat, Level first then Spirit:
-<pre>{ { type = "Level", value = 1.5 }, { type = "Spirit", value = 0.04 } }</pre>
-Absent and zero scalings are omitted, so an empty list means the stat does not scale.
-====Parameters====
-* '''hero_data''' - Hero table
-* '''stat''' - Key of the stat
-* '''include_zero''' - OPTIONAL, keep scalings whose value is 0. Only get_hero_scaling_data needs this.
-=== has_stat ===
-Returns true when a hero has a non-zero base value for a stat, or any scaling for it. Backs hero_has_stat.
-====Parameters====
-* '''hero_data''' - Hero table
-* '''stat''' - Key of the stat
-=== find_hero_key ===
-Resolves a hero key or an english hero name to a hero key, case-insensitively. Returns nil when the input matches no hero. Backs get_hero_key and resolve_key.
-====Parameters====
-* '''input''' - Hero key or english hero name
-=== hero_tag ===
-Returns a hero's Nth description tag, or an empty string when there is no such tag. Backs get_hero_tag and has_tags.
-====Parameters====
-* '''hero_en''' - Name of the hero in english
-* '''index''' - Which tag to return (1, 2 or 3)
-=== write_scalar_str ===
-Returns the expanded <code>Ss</code> or <code>PI</code> template for a scaling value, or an empty string when the value is 0.
-====Parameters====
-* '''scaling_value''' - The scaling amount
-* '''scaling_type''' - "Spirit" or "Level"
-* '''compact''' - OPTIONAL, render the compact form with the value shown
-=== get_hero_scaling_data ===
-'''Deprecated''', use get_scalings instead. Returns a table keyed by scaling value, so an entry is silently dropped when Level and Spirit scale by the same amount, and zero scalings are kept. Retained only for [[Module:HeroComparisonTable]].
 ====Parameters====
-* '''hero_data''' - Hero table
+* '''property''' - Property key to search for
-* '''stat''' - Key of the stat
 == Scaling System ==