Naming convention for Named values

Creation, discussion, and balancing of game content such as techs, buildings, ship parts.

Moderators: Oberlus, Committer

Post Reply
Message
Author
User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Naming convention for Named values

#1 Post by Oberlus »

Named values (NamedReal, NamedInteger) will be used a lot in stringtables to show numbers calculated from game settings and to facilitate scripting changes. E.g. the research bonus from a Algorithmic Elegance depends on a number written in the tech file and a configurable macro (RESEARCH_PER_POP).
Without Named values, if a modder changes the value in the tech file, s/he also needs to update the corresponding entry in the English stringtable, and the traductors have to update the other stringtables too; or if one changes the default RESEARCH_PER_POP, the values in the stringtable file will be wrong until updates, and when getting back to default values the stringtable would be incorrect again.
With Named values you just change the number in the FOCS file (the macro or the tech bonus) and everything will be correct.

Surprisingly, the Named values require unique names. The minimum is calling them with (most of) the tech (policy/building/...) name, plus something else to differentiate from the tech itself. For example adding "_EFFECT":
BLD_AUTO_HISTORY_ANALYSER -> BLD_AUTO_HISTORY_ANALYSER_EFFECT

What if the source has more than one bonus?

Easy, indicate also the affected meter:
LRN_SOME_TECH -> LRN_SOME_TECH_RESEARCH_EFFECT and LRN_SOME_TECH_TWERK_EFFECT

Differentiating by Target/Max and Current meters?

Of course:
LRN_SOME_TECH -> LRN_SOME_TECH_TARGET_RESEARCH_EFFECT and LRN_SOME_TECH_MAXTWERK_EFFECT

What about bonus per population, flat and scaling?

Ah, sure, indicate those too:
LRN_SOME_TECH -> LRN_SOME_TECH_TARGET_RESEARCH_PERPOP_EFFECT and LRN_SOME_TECH_MAXTWERK_FLAT_EFFECT

What if it is a malus instead of a bonus?

Right, change EFFECT for MALUS/BONUS:
LRN_SOME_TECH -> LRN_SOME_TECH_TARGET_RESEARCH_PERPOP_BONUS and LRN_SOME_TECH_MAXTWERK_FLAT_MALUS

Cool, let's see how it fits in the FOCS files. Without Named values:

Code: Select all

SetTargetResearch = Value + Target.Population *  5 * [[RESEARCH_PER_POP]])
With Named values:

Code: Select all

SetTargetResearch = Value + Target.Population * (NamedReal name = "LRN_SOME_TECH_TARGET_RESEARCH_PERPOP_BONUS" value = (5 * [[RESEARCH_PER_POP]])
Hey, we forgot to add indications on priority precedence, it is not the same flat bonus before than after scaling priority. Also now we have a second scaling priority.

...


More seriously now, we could stablish some naming conventions for this kind of things. Words like TARGET_RESEARCH could be abbreviated to TARRES (TARIND, TARINF, TARPOP, MAXDEF, MAXTRP, MAXSHL).
Even... the techs and buildings could be given a naming convention: e.g. BLD_XX_AUTO_HISTORY_ANALYSER, so that the XX part is brief, unique and informative of tech tree location and level/tier, and the rest (_AUTO_HISTORY_ANALYSER) can be stripped from things like accounting labels, named values, etc. to get something like BLD_CON1_TARRES_FLAT_PRESCL_BONUS.

Or, we let this kind of labels be named however the contributor introducing it feels like, longer or shorter, more informative or less, judging by the circumstances.

Or we choose minimalism in naming and ask for the shortest possible label that includes the source name.

Thoughts?

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: Naming convention for Named values

#2 Post by Geoff the Medio »

Oberlus wrote: Wed Oct 21, 2020 4:54 pmWords like TARGET_RESEARCH could be abbreviated to TARRES (TARIND, TARINF, TARPOP, MAXDEF, MAXTRP, MAXSHL).
Ugh, please no. Don't make someone reading text / a script have to stop to look up what abbreviations stand for.
Even... the techs and buildings could be given a naming convention: e.g. BLD_XX_AUTO_HISTORY_ANALYSER, so that the XX part is brief, unique and informative of tech tree location and level/tier, and the rest (_AUTO_HISTORY_ANALYSER) can be stripped from things like accounting labels, named values, etc. to get something like BLD_CON1_TARRES_FLAT_PRESCL_BONUS.
How much of this really needs to be indicated in a lookup reference name? Tier isn't even a thing yet. What does it matter what tech a building is associated with? Actually, it's probably better to not mention where on the tech tree a building or policy or part is, since that would make moving stuff elsewhere in the tree more complicated, as a bunch of internal-to-the building script labels would need updating.
Or, we let this kind of labels be named however the contributor introducing it feels like, longer or shorter, more informative or less, judging by the circumstances.
Is this necessarily a problem?

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: Naming convention for Named values

#3 Post by Oberlus »

OK, no abbreviations and no info on category or "level".
Geoff the Medio wrote: Wed Oct 21, 2020 5:46 pm
Or, we let this kind of labels be named however the contributor introducing it feels like, longer or shorter, more informative or less, judging by the circumstances.
Is this necessarily a problem?
I don't think it is a problem. But we can get to the point where some contributors want to name stuff this or that way in ther PRs, and some other contributors will present objections while reviewing, and you could say something like "I'm reluctant to merge this before consensus". But in those cases I guess we can just finish whatever discussion seems necessary and reach consensus whenever it's needed, nothing critical will be delayed.

Ophiuchus
Programmer
Posts: 3433
Joined: Tue Sep 30, 2014 10:01 am
Location: Wall IV

Re: Naming convention for Named values

#4 Post by Ophiuchus »

Oberlus wrote: Wed Oct 21, 2020 4:54 pm Or, we let this kind of labels be named however the contributor introducing it feels like, longer or shorter, more informative or less, judging by the circumstances.

Or we choose minimalism in naming and ask for the shortest possible label that includes the source name.

Thoughts?
The named values are basically global constants. Having long names is not a problem here. So no abbreviations. Characters do not cost anything.

I think introducing best practices by using good names would be best.
And by good I mean that one compare a name and the surrounding code and see if those fit together - in AI we basically copy the operations from the FOCS code to make predictions.

We need unique names, so using the underlying content for that is a simple way to enforce that.

If we are very strict and have a structure/pattern for naming, (not very likely) we can use that in python scripting. E.g. something similar to

Code: Select all

research_pop_multipliers = {k:v for (k,v) in named_values.items() if v.ends_with "RESEARCH_PERPOP"}
Any code or patches in anything posted here is released under the CC and GPL licences in use for the FO project.

Look, ma... four combat bouts!

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: Naming convention for Named values

#5 Post by Oberlus »

Ophiuchus wrote: Wed Oct 21, 2020 9:25 pm If we are very strict and have a structure/pattern for naming, (not very likely) we can use that in python scripting. E.g. something similar to

Code: Select all

research_pop_multipliers = {k:v for (k,v) in named_values.items() if v.ends_with "RESEARCH_PERPOP"}
In that case I bet the best is to include all the relevant information in the name (such as (TARGET_)RESEARCH/INDUSTRY/... and PERPOP/FLAT/SCALING).
Will it be relevant to distinguish if it is BONUS or MALUS or can that be filtered checking the sign of the values in named_values?

Ophiuchus
Programmer
Posts: 3433
Joined: Tue Sep 30, 2014 10:01 am
Location: Wall IV

Re: Naming convention for Named values

#6 Post by Ophiuchus »

Oberlus wrote: Thu Oct 22, 2020 2:58 pm
Ophiuchus wrote: Wed Oct 21, 2020 9:25 pm If we are very strict and have a structure/pattern for naming, (not very likely) we can use that in python scripting. E.g. something similar to

Code: Select all

research_pop_multipliers = {k:v for (k,v) in named_values.items() if v.ends_with "RESEARCH_PERPOP"}
In that case I bet the best is to include all the relevant information in the name (such as (TARGET_)RESEARCH/INDUSTRY/... and PERPOP/FLAT/SCALING).
Will it be relevant to distinguish if it is BONUS or MALUS or can that be filtered checking the sign of the values in named_values?
It can be flat (actually flat is better than bonus/malus). In the AI one would simply add it, if it is negative it will decrease the value.

If we have multiple layers of additions/multiplication this information would also need to be somewhere. Not sure this is worth it.
Any code or patches in anything posted here is released under the CC and GPL licences in use for the FO project.

Look, ma... four combat bouts!

Post Reply