Module:AbilityTable/Lists/doc: Difference between revisions

(2 intermediate revisions by 2 users not shown)

Line 1:

== How to add a missing ability to a list ==

== Common Scenarios ==

=== How to add a missing ability to a list ===

If an ability should appear in a table but doesn't, it means none of its data properties match the list's property keys. The recommended fix is to find a matching property in [[Data:AbilityData.json]] and add it to the list. Only use a raw ability name as a fallback if no suitable property exists.

Line 6:

Line 8:

'''Finding the right property''': Open [[Data:AbilityData.json]] and search for the ability. Look through its properties for one that represents the relevant mechanic, for example, a silence ability might have <code>SilenceDuration</code>. A good property is one shared by many abilities with the same mechanic, not something unique to one ability.

If a property is shared by many abilities but only some of them have the value you care about, use the <code>Key:Value</code> form to narrow it down. Ability scaling is the usual case: nearly every ability has a <code>Scale</code>, so <code>Scale.Type:cooldown</code> is what separates the ones that scale with [[Ability Cooldown]] from the rest.

After adding the property or ability name, test the table to make sure no unwanted extra abilities appeared. If they did, the property is too broad, consider using a raw ability name instead, or adding the extras to <code>exclude_abilities</code>.

Line 11:

Line 15:

If your new ability has special column values, you may also want to update [[Module:AbilityTable/ComplexRenderers]]. And if it needs a descriptive note, add it in [[Module:AbilityTable/Notes]].

=== Example: adding ~~a missing ability~~ to the healreduce list ===

==== Example: adding Affliction to the "healreduce" list ====

Say {{AbilityIcon|Affliction}} is missing from the heal reduction table. First, check the comment above <code>["healreduce"]</code> in the module, it says "Abilities that reduce healing on their targets", so Affliction belongs there.

Line 27:

Line 31:

Save and test the table with <code><nowiki>{{AbilityTable|healreduce}}</nowiki></code>. Affliction now appears, and no unexpected abilities were added, so the property was a good fit.

== How to exclude an ability from a list ==

=== How to exclude an ability from a list ===

If an ability appears in a table but shouldn't, first check whether the property causing the match actually belongs in the list. If several unrelated abilities are showing up as false positives, it's likely that a prop was added to the list by mistake — inspect the list carefully and consider removing it. Make sure to test after removing a prop to confirm you didn't accidentally drop any legitimate abilities.

If an ability appears in a table but shouldn't, first check whether the property causing the match actually belongs in the list. If several unrelated abilities are showing up as false positives, it's likely that a prop was added to the list by mistake, inspect the list carefully and consider removing it. Make sure to test after removing a prop to confirm you didn't accidentally drop any legitimate abilities.

If the false positive is a genuine exception — the prop belongs in the list but this one ability happens to match it incorrectly — then add the ability to <code>exclude_abilities</code> under the relevant list name with a comment explaining why:

If the false positive is a genuine exception, the prop belongs in the list but this one ability happens to match it incorrectly, then add the ability to <code>exclude_abilities</code> under the relevant list name with a comment explaining why:

<pre>

Line 39:

Line 43:

</pre>

== How to add a new list ==

=== How to add a new list ===

Adding a new list makes a new ability table available via <code><nowiki>{{AbilityTable|listname}}</nowiki></code>.

Line 52:

Line 56:

</pre>

Test the result with <code><nowiki>{{AbilityTable|mylist}}</nowiki></code> and adjust until the list looks right — adding missing abilities and excluding false positives as described above.

Test the result with <code><nowiki>{{AbilityTable|mylist}}</nowiki></code> and adjust until the list looks right, adding missing abilities and excluding false positives as described above.

'''Step 3 (optional)''': If the table should have extra columns beyond Notes, register a renderer in [[Module:AbilityTable]] and implement it in [[Module:AbilityTable/ComplexRenderers]].

'''Step 4 (optional)''': Add human notes for specific abilities in [[Module:AbilityTable/Notes]].

== Technical ==

=== How targets are matched ===

Every entry in a list is a ''target'': a string matched against each ability record in [[Data:AbilityData.json]]. There are four forms.

{| class="wikitable"

! Form !! Example !! Matches when

|-

| Plain name

| <code>SilenceDuration</code>, <code>Card Trick</code>

| a property with that name exists anywhere in the record and holds a non-zero, non-empty value, ''or'' the string appears as a value anywhere in the record. Raw ability names work because the ability's <code>Name</code> is such a value.

|-

| Name with a value

| <code>Type:spirit</code>

| a property with that name exists anywhere in the record and its own value is <code>spirit</code>

|-

| Nested path

| <code>AbilityDuration.Scale.Type</code>

| that exact chain of properties exists and ends in a non-zero, non-empty value

|-

| Nested path with a value

| <code>Scale.Type:cooldown</code>

| that chain exists and ends in <code>cooldown</code>

|}

A few details worth knowing:

* '''A property's value is its own value, not anything nested inside it.''' Damage is stored as <code>{ "Value": 90, "Scale": { "Type": "spirit" } }</code>, so <code>Damage:90</code> matches it but <code>Damage:spirit</code> does not, the <code>spirit</code> sits on a different property. Use <code>Damage.Scale.Type:spirit</code> for that.

* '''Paths step through lists.''' <code>Upgrades.Damage</code> matches if ''any'' upgrade has a Damage value; <code>Upgrades.1.Damage</code> checks only the first upgrade.

Module:AbilityTable/Lists/doc: Difference between revisionsGive feedback

Vergir (talk | contribs)

@@ Line 1: / Line 1: @@
-== How to add a missing ability to a list ==
+== Common Scenarios ==
+=== How to add a missing ability to a list ===
 If an ability should appear in a table but doesn't, it means none of its data properties match the list's property keys. The recommended fix is to find a matching property in [[Data:AbilityData.json]] and add it to the list. Only use a raw ability name as a fallback if no suitable property exists.
@@ Line 6: / Line 8: @@
 '''Finding the right property''': Open [[Data:AbilityData.json]] and search for the ability. Look through its properties for one that represents the relevant mechanic, for example, a silence ability might have <code>SilenceDuration</code>. A good property is one shared by many abilities with the same mechanic, not something unique to one ability.
+If a property is shared by many abilities but only some of them have the value you care about, use the <code>Key:Value</code> form to narrow it down. Ability scaling is the usual case: nearly every ability has a <code>Scale</code>, so <code>Scale.Type:cooldown</code> is what separates the ones that scale with [[Ability Cooldown]] from the rest.
 After adding the property or ability name, test the table to make sure no unwanted extra abilities appeared. If they did, the property is too broad, consider using a raw ability name instead, or adding the extras to <code>exclude_abilities</code>.
@@ Line 11: / Line 15: @@
 If your new ability has special column values, you may also want to update [[Module:AbilityTable/ComplexRenderers]]. And if it needs a descriptive note, add it in [[Module:AbilityTable/Notes]].
-=== Example: adding a missing ability to the healreduce list ===
+==== Example: adding Affliction to the "healreduce" list ====
 Say {{AbilityIcon|Affliction}} is missing from the heal reduction table. First, check the comment above <code>["healreduce"]</code> in the module, it says "Abilities that reduce healing on their targets", so Affliction belongs there.
@@ Line 27: / Line 31: @@
 Save and test the table with <code><nowiki>{{AbilityTable|healreduce}}</nowiki></code>. Affliction now appears, and no unexpected abilities were added, so the property was a good fit.
-== How to exclude an ability from a list ==
+=== How to exclude an ability from a list ===
-If an ability appears in a table but shouldn't, first check whether the property causing the match actually belongs in the list. If several unrelated abilities are showing up as false positives, it's likely that a prop was added to the list by mistake — inspect the list carefully and consider removing it. Make sure to test after removing a prop to confirm you didn't accidentally drop any legitimate abilities.
+If an ability appears in a table but shouldn't, first check whether the property causing the match actually belongs in the list. If several unrelated abilities are showing up as false positives, it's likely that a prop was added to the list by mistake, inspect the list carefully and consider removing it. Make sure to test after removing a prop to confirm you didn't accidentally drop any legitimate abilities.
-If the false positive is a genuine exception — the prop belongs in the list but this one ability happens to match it incorrectly — then add the ability to <code>exclude_abilities</code> under the relevant list name with a comment explaining why:
+If the false positive is a genuine exception, the prop belongs in the list but this one ability happens to match it incorrectly, then add the ability to <code>exclude_abilities</code> under the relevant list name with a comment explaining why:
 <pre>
@@ Line 39: / Line 43: @@
 </pre>
-== How to add a new list ==
+=== How to add a new list ===
 Adding a new list makes a new ability table available via <code><nowiki>{{AbilityTable|listname}}</nowiki></code>.
@@ Line 52: / Line 56: @@
 </pre>
-Test the result with <code><nowiki>{{AbilityTable|mylist}}</nowiki></code> and adjust until the list looks right — adding missing abilities and excluding false positives as described above.
+Test the result with <code><nowiki>{{AbilityTable|mylist}}</nowiki></code> and adjust until the list looks right, adding missing abilities and excluding false positives as described above.
 '''Step 3 (optional)''': If the table should have extra columns beyond Notes, register a renderer in [[Module:AbilityTable]] and implement it in [[Module:AbilityTable/ComplexRenderers]].
 '''Step 4 (optional)''': Add human notes for specific abilities in [[Module:AbilityTable/Notes]].
+== Technical ==
+=== How targets are matched ===
+Every entry in a list is a ''target'': a string matched against each ability record in [[Data:AbilityData.json]]. There are four forms.
+{| class="wikitable"
+! Form !! Example !! Matches when
+|-
+| Plain name
+| <code>SilenceDuration</code>, <code>Card Trick</code>
+| a property with that name exists anywhere in the record and holds a non-zero, non-empty value, ''or'' the string appears as a value anywhere in the record. Raw ability names work because the ability's <code>Name</code> is such a value.
+|-
+| Name with a value
+| <code>Type:spirit</code>
+| a property with that name exists anywhere in the record and its own value is <code>spirit</code>
+|-
+| Nested path
+| <code>AbilityDuration.Scale.Type</code>
+| that exact chain of properties exists and ends in a non-zero, non-empty value
+|-
+| Nested path with a value
+| <code>Scale.Type:cooldown</code>
+| that chain exists and ends in <code>cooldown</code>
+|}
+A few details worth knowing:
+* '''A property's value is its own value, not anything nested inside it.''' Damage is stored as <code>{ "Value": 90, "Scale": { "Type": "spirit" } }</code>, so <code>Damage:90</code> matches it but <code>Damage:spirit</code> does not, the <code>spirit</code> sits on a different property. Use <code>Damage.Scale.Type:spirit</code> for that.
+* '''Paths step through lists.''' <code>Upgrades.Damage</code> matches if ''any'' upgrade has a Damage value; <code>Upgrades.1.Damage</code> checks only the first upgrade.