Page MenuHomeWildfire Games

standardized hero aura descriptions
Needs ReviewPublic

Authored by Nescio on Apr 1 2019, 1:02 PM.

Details

Reviewers
Gallaecio
Summary

This patch rephrases the aura descriptions of hero auras to an uniform standard, to ensure descriptions follow the actual modifications: [player] [class] [change] [attributes], e.g. "Spearmen +1.0 capture attack strength and +25% melee attack damage." instead of "+25% attack and +1 capture for spear soldiers."

See also D1720, D1806, D1807.

The formation and garrison type aura descriptions are ugly; improvement suggestions are welcome.

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 7077
Build 11558: Vulcan BuildJenkins
Build 11557: arc lint + arc unit

Event Timeline

Vulcan added a subscriber: Vulcan.Apr 1 2019, 1:46 PM

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

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

I’ve left a few comments, but I must say I love these changes overall.

binaries/data/mods/public/simulation/data/auras/units/heroes/athen_hero_iphicrates_1.json
12

I’m don’t have a strong feeling against it, but… why 3.0 instead of 3?

binaries/data/mods/public/simulation/data/auras/units/heroes/athen_hero_themistocles_1.json
11

When singular, I think we need to use ‘the’: ‘Ship’ → ‘The ship’.

Also, I’m unsure about ‘he is garrisoned in’, specially because of the ‘in’ at the end. What would you think about ‘where he is garrisoned’?

Finally, specially to make sentences like this one more readable, what would you think about adding a ‘get(s)’ to the structure? So, from the current “[player] [class] [change] [attributes]” to “[player] [class] get(s) [change] [attributes]”.

Altogether, the result here would be “The ship where he is garrisoned gets −30% batch training time and +50% movement speed.”.

Nescio added a comment.EditedSat, Jul 20, 8:06 PM

As for +3.0 vs +3, I have no strong preference, provided it is done consistently. The gui displays armour with one decimal, though:

Most auras are of the global or range type; formulating those is straightforward. However, there are a few other aura types, which are more problematic:

"type": "formation":
units/heroes/athen_hero_iphicrates_1.json

"type": "garrison":
units/heroes/maur_hero_chanakya_1.json
units/heroes/iber_hero_caros_1.json
units/heroes/athen_hero_themistocles_1.json
units/heroes/hero_garrison.json

"type": "garrisonedUnits":
structures/cart_super_dock_repair.json
structures/wall_garrisoned.json
structures/workshop_repair.json

"type": "player":
units/catafalques/sele_catafalque_2.json
structures/wonder_pop_1.json
structures/wonder_pop_2.json
teambonuses/ptol_player_teambonus.json
teambonuses/mace_player_teambonus.json

So perhaps it would be best to settle upon a generic scheme for those and then apply it?

[EDIT]: Furthermore, this should probably be rebased because of edits in the intervening months.
Also, shouldn't classes be capitalized? (My mistake, I believe.)

So perhaps it would be best to settle upon a generic scheme for those and then apply it?

Any ideas?

Looking at the April 1 version:
formation type: [class] in his formation [change] [attributes]
garrison type: [class] he is garrison in [change] [attributes]
garrisoned type: Garrisoned [class] [change] [attributes]

improvement suggestions are welcome

still applies :)

Things to be decided upon before I'll update this patch:

  • +1 or +1.0 armour?
  • should classes be capitalized or not?
  • formation, garrison, and garrisoned aura description format.
In D1808#87832, @Nescio wrote:

Things to be decided upon before I'll update this patch:

  • +1 or +1.0 armour?
  • should classes be capitalized or not?
  • I think we should avoid trailing zeroes on user-visible text for now. I would not mind adding extra zeroes for values where a maximum number of decimals has been chosen, but even if we decide to go that path for certain values I would do so in a separate patch.
  • I would postpone this decision as well. The current style guide says capitalized (full disclosure: I wrote that), but I would not enforce that as part of this patch. I would leave the capitalization as it currently is in the aura descriptions, and have a separate, later patch to enforce either capitalized or non-capitalized style in every non-flavor user-visible string.
In D1808#87832, @Nescio wrote:
  • formation, garrison, and garrisoned aura description format.

I think you already nailed garrisoned type: Garrisoned [class] [change] [attributes]

As for the other two, I have 2 suggestions for formation and 1 for garrison:
formation type: Formation [class] [change] [attributes] or Accompanying [class] [change] [attributes]
garrison type: Hosting [class] [change] [attributes]

binaries/data/mods/public/simulation/data/auras/units/heroes/maur_hero_chanakya_1.json
11

It’s missing a closing period.

elexis added a subscriber: elexis.Sun, Jul 21, 1:20 PM

should classes be capitalized or not?

I remember that this already was practice to capitalize them and remember changing things to account for that - Spearman, Infantry. You may find some evidence for that in the files? Wondering why they're not standardized already.
The reason for that was mostly that one didn't mean the common noun but the proper noun (And I recall that these words were also used in the related discussions) - for example Boudicca is female but not Female.
I find D464 where common nouns were proponed for consistency apparently. But I recall sycthetwirler changing things for proper nouns in one of the Changelogs pages.
Those classes are identity classes, so in the tooltip they also appear as Spearman etc., so it seems like one is the right way and the other is the consistent way?

I think we should avoid trailing zeroes on user-visible text for now.

Agreed. In that case the GUI should probably be edited to not add any trailing zeroes for e.g. armour either (in a different patch, of course).

should classes be capitalized or not?

I would postpone this decision as well.

I don't think postponing that decision is a good idea. Everytime a string is updated, the entire string has to be re-translated again for all languages, which means that changing capitalization later doubles the work-load for our translators. Besides, the purpose of this patch is to improve consistency, and a policy to keep it uncapitalized in some data files while demanding it to be capitalized elsewhere doesn't seem very consistent.

I just had a quick look at some technologies (because those are the data files closest to auras) and it seems there is no class capitalization consistency there either. E.g. rP15713 introduced five years ago
simulation/data/technologies/armor_cav_01.json with:
"tooltip": "Equip your cavalry mounts with armor. All Cavalry +1 Hack and Pierce armor level.",
but also:
speed_cavalry_01.json with:
"tooltip": "+10% cavalry walk speed.",

Nescio added a comment.EditedSun, Jul 21, 3:49 PM

The aura description formats should be clear and unambiguous.

garrisoned type: Garrisoned [class] [change] [attributes]

Agreed.

garrison type: Hosting [class] [change] [attributes]

E.g. “Hosting warship +10% health.” Would the uninformed player understand that means the hero is to be garrisoned?

formation type: Formation [class] [change] [attributes] or Accompanying [class] [change] [attributes]

E.g. “Formation spearmen +10% health.” Wouldn't that imply all spearmen in any formation, rather than only spearmen in the formation containing the aura-entity (e.g. hero)?
E.g. “Accompanying spearmen +10% health.” Again, how is the player supposed to know that means only spearmen in the hero's formation?

[EDIT]: How about “His formation's [class] [change] [attributes]”?

In D1808#87907, @Nescio wrote:

garrison type: Hosting [class] [change] [attributes]

E.g. “Hosting warship +10% health.” Would the uninformed player understand that means the hero is to be garrisoned?

formation type: Formation [class] [change] [attributes] or Accompanying [class] [change] [attributes]

E.g. “Formation spearmen +10% health.” Wouldn't that imply all spearmen in any formation, rather than only spearmen in the formation containing the aura-entity (e.g. hero)?
E.g. “Accompanying spearmen +10% health.” Again, how is the player supposed to know that means only spearmen in the hero's formation?

I agree with all your points. Those are just the best things I could think so far that are reasonably short.

[EDIT]: How about “His formation's [class] [change] [attributes]”?

In addition to the need to handle His/Her, which I would try to avoid, this option would have the same problem as e.g. “Same formation [class] [change] [attributes]”: it’s possible to think that any units using the same type of formation as the hero get the benefit.

Maybe what we need first is to have two completely different words to refer to (1) formation as in a way a group of units can organize themselves and (2) formation as in a specific group of units. For example, if we used ‘group’ for the latter, “Same group [class] [change] [attributes]” may work.

Before I can update this, we still need to find a proper format for the formation and garrison aura types.

Maybe what we need first is to have two completely different words to refer to (1) formation as in a way a group of units can organize themselves and (2) formation as in a specific group of units. For example, if we used ‘group’ for the latter, “Same group [class] [change] [attributes]” may work.

A group is an arbitrary selection of entities, which can be defined by e.g. Ctrl+1 and selected by pressing 1 or clicking on the group panel at the left of the screen.

In D1808#90733, @Nescio wrote:

Before I can update this, we still need to find a proper format for the formation and garrison aura types.

Maybe what we need first is to have two completely different words to refer to (1) formation as in a way a group of units can organize themselves and (2) formation as in a specific group of units. For example, if we used ‘group’ for the latter, “Same group [class] [change] [attributes]” may work.

A group is an arbitrary selection of entities, which can be defined by e.g. Ctrl+1 and selected by pressing 1 or clicking on the group panel at the left of the screen.

OK, so group is not an option. We could use “formation type” or “type of formation” for 1, and hope that people won’t ocnfuse it with “formation” (2). But I would really prefer to have a different word for either 1 or 2.