Page MenuHomeWildfire Games

standardized structure aura descriptions
Needs ReviewPublic

Authored by Nescio on Apr 1 2019, 11:29 AM.

Details

Reviewers
Gallaecio
Summary

This patch rephrases the aura descriptions of structure auras (and also the female inspiration aura) to an uniform standard, to ensure descriptions follow the actual modifications: [class] [change] [attributes], e.g. "Garrisoned ships +10.0 health regeneration rate." instead of "Repairs garrisoned ship at 10 HP per second."

See also D1720, D1807, D1808.

Test Plan

Check for mistakes and omissions.

Diff Detail

Repository
rP 0 A.D. Public Repository
Branch
/ps/trunk
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 7074
Build 11552: Vulcan BuildJenkins
Build 11551: arc lint + arc unit

Event Timeline

Nescio created this revision.Apr 1 2019, 11:29 AM
Vulcan added a subscriber: Vulcan.Apr 1 2019, 1:38 PM

Successful build - Chance fights ever on the side of the prudent.

Link to build: https://jenkins.wildfiregames.com/job/differential/1146/display/redirect

elexis added a subscriber: elexis.Apr 3 2019, 11:14 PM

What's the benefit to having .0? Didn't it use round numbers everywhere?

Stan added a subscriber: Stan.Apr 4 2019, 8:52 AM

I don't think there is any benefit. Unless JavaScript does some weird cast when it's not there ?

Do you mean the .0 in the aura descriptions? Good question. Not all additions are integers; e.g. the brit_hero_cunobelin.json aura has:

		{ "value": "Health/RegenRate", "add": 0.8 }

For consistency I chose to give all added numbers a decimal. Besides, it also helps differentiating addition (e.g. +10.0) from multiplication (e.g. +10%).
https://trac.wildfiregames.com/wiki/EnglishStyleGuide doesn't say how to format numbers in strings, so I suppose it can be argued it's a matter of personal taste. It would make sense to decide upon a standard, though.

elexis added a comment.Apr 4 2019, 2:59 PM

That .8 was necessary because its a really powerful effect (healing 200 units nearby simultaneously) and it degenerated the game balance towards people always having to train the unit.
The question is whether that one unit having one more digit than all the others makes it right to change all the others.
What if an upcoming template change uses 0.75?
If the objective of this diff to achieve consistency, one can also use consistently avoid trailing zeroes.

I guess the additional benefit of the trailing zeroes could be to inform the reader of the value range of the tech/aura effect.
Reading 1.0 informs him it could also be 1.1 for the next tech but not 1.05;
whereas 1 leaves the reader surprised if he encounters cunobelins unique 0.8?

One might even become suspicious and wonder whether the 0.8 was a good idea or whether the aura bonus shouldn't be restricted differently. I don't know if that cunobelin fix was the best idea out there, but he needed a nerf for sure and I wanted to be conservative in the gameplay changes.

There is #3972 in which I thought to propose using sprintf syntax for these strings.

So instead of

"auraDescription": "Citizen-soldiers +10% build rate and resource gather speed.",

it would say

"auraDescription": {

"string": "Citizen-soldiers +%(rate)s%% build rate and resource gather speed.",
"values": {
    "rate": "Builder/Rate"
 }

or something like that.

Then none of the descriptions are wrong, one can change the numbers without breaking the description, and one can change the number format for all strings without changing the strings.
Looks like having the problem that we want 10%, not 1.1, but that should be obtainable.

− vs. - also a bit meh, but the problem is more that the character is not commonly used if it is really considered different from hypen. In programming languages we use hyphen to express subtraction, and minus isn't on our keyboards. Needs to fix society, and I guess we can start fixing society by fixing 0ad first.

Nescio added a comment.Apr 4 2019, 3:21 PM

Personally I think it's perfectly fine some modifications use decimals; there is no reason why every addition should be an integer.
Concerning your trailing zeroes point, for me .0 indicates the number can be a decimal, but not necessarily that it is limited to exactly one decimal.

As for minus versus hyphen, the game can properly display many Unicode characters, therefore there is no reason why user-facing text strings should be limited to ascii only.

#3972 is interesting, but it also makes things less obvious for people who don't know JavaScript. Besides, what to do with technologies with multiple modifications? E.g.

{
  "affects": ["Mercenary"],
  "autoResearch": true,
  "genericName": "Mercenary Units",
  "modifications": [
    {"value": "Attack/Capture/Value",         "multiply": 1.15, "affects": "Soldier"         },
    {"value": "Attack/Melee/Crush",           "multiply": 1.10, "affects": "Melee Elephant"  },
    {"value": "Attack/Melee/Crush",           "multiply": 1.15, "affects": "Melee !Elephant" },
    {"value": "Attack/Melee/Hack",            "multiply": 1.15, "affects": "Melee"           },
    {"value": "Attack/Melee/Pierce",          "multiply": 1.15, "affects": "Melee"           },
    {"value": "Attack/Melee/Thrust",          "multiply": 1.15, "affects": "Melee"           },
    {"value": "Attack/Ranged/Crush",          "multiply": 1.15, "affects": "Ranged"          },
    {"value": "Attack/Ranged/Hack",           "multiply": 1.15, "affects": "Ranged"          },
    {"value": "Attack/Ranged/Pierce",         "multiply": 1.15, "affects": "Ranged"          },
    {"value": "Attack/Ranged/Thrust",         "multiply": 1.15, "affects": "Ranged"          },
    {"value": "Cost/BuildTime",               "multiply": 0.5                                },
    {"value": "Cost/Resources/food",          "replace":  0                                  },
    {"value": "Cost/Resources/metal",         "replace":  0                                  },
    {"value": "Cost/Resources/silver",        "multiply": 2.0                                },
    {"value": "Cost/Resources/stone",         "replace":  0                                  },
    {"value": "Cost/Resources/wood",          "replace":  0                                  },
    {"value": "Health/Max",                   "multiply": 1.1                                }
  ],
  "tooltip": "Mercenaries have +100% silver cost, 0 other resource costs, −50% training time, +10% health, +15% capture attack strength, +15% melee and ranged attack damage."
}
elexis added a comment.Apr 5 2019, 2:43 AM

The tooltip lies about elephants, quite a stuffed tech, but it should still work out, the part +15% melee and ranged attack damage could be +%(AttackMeleeHack)s%% melee and ranged attack damage, still seems less than more likely to mess up the numbers, as one now only needs to compare that ranged and melee attack is the same, instead of testing that ranged and melee attack and the number in the tooltip are the same?

Concerning your trailing zeroes point, for me .0 indicates the number can be a decimal, but not necessarily that it is limited to exactly one decimal.

Why is the format is used if it's not that?

Why is the format is used if it's not that?

For some people +1 might imply everything is an integer, which is not necessarily true. Anyway, if you think it's better to remove the .0 then I can do that.

The tooltip lies about elephants, quite a stuffed tech, but it should still work out, the part +15% melee and ranged attack damage could be +%(AttackMeleeHack)s%% melee and ranged attack damage, still seems less than more likely to mess up the numbers, as one now only needs to compare that ranged and melee attack is the same, instead of testing that ranged and melee attack and the number in the tooltip are the same?

In the example “+15% melee and ranged attack damage” groups nine modifications; AttackMeleeHack is just one value; so if only that value is changed, the statement is no longer true, because the other damage types are unchanged, thus the editor will still have to rephase the tooltip when he change a modification.
Of course, if there is exactly one phrase per statement, then it's not necessary to update the tooltip with your suggestion, but then the total sentence will be much longer and thus more time-consuming to read and understand, which is problematic for players in game.
Another example: team and civ bonuses; they are also listed in the civ files. Right now if one is changed the editor updates the tooltip in the technology file and can copy-paste it to the description in the civilization file; anyone can see at a glance if they're the same. With your suggestion, the tooltip in the bonus file no longer has to be updated, but the description in the civ file still does, since they're no longer identical.
Besides, how often are values actually changed?

bb added a subscriber: bb.Apr 6 2019, 4:02 PM
bb added inline comments.
binaries/data/mods/public/simulation/data/auras/structures/kush_temple_amun.json
8

Just want to make sure the following is considered:
this tooltip contains besides the effect also some historical reference, this patch deletes all those. Now I totally understand the complete irrelevance for gameplay of these referneces, however having such an explanation in a structree or unit viewer is a nice feature.