[Question] Coding Configurable Variables in OXCE

[WarStalkeR]

When in Matrix chat I was discussing OXCE coding related stuff, Yankes advised to me use `constants` for new variables that I added.

And here comes the question (mostly for you, Meridian):
1) When should I place configurable variables into `constants`, to call them via `Mod::VARIABLE_NAME`?
2) When should I place configurable variables into `fixedUserOptions`, to call them via `Options::VARIABLE_NAME`?
3) When should I place configurable variables into `Mod.cpp/h` directly, in order to call them via `_game->getMod()->getVariableValue()`?

I'm trying to make for myself some kind of coding categorization, which will help me to decide, where to put new configurable variables.

[Meridian]

3) When should I place configurable variables into `Mod.cpp/h` directly, in order to call them via `_game->getMod()->getVariableValue()`?

Preferably never.
(but exceptions will always exist)

2) When should I place configurable variables into `fixedUserOptions`, to call them via `Options::VARIABLE_NAME`?

I assume you mean into "Options.inc.h".
(you should not put anything into "fixedUserOptions" as a DEV, that's for modders to do, and even they should have a good reason)

You should put user options into "Options.inc.h"... things which are either QoL, cosmetic or other optional features... which DON'T have any impact on game mechanics.
(anything that has impact on game mechanics is a modder option and should be put into the ruleset, NOT into user options)

1) When should I place configurable variables into `constants`, to call them via `Mod::VARIABLE_NAME`?

If there is no better place in the ruleset, where you would put it.

[Yankes]

Preferably never.
(but exceptions will always exist)

I assume you mean into "Options.inc.h".
(you should not put anything into "fixedUserOptions" as a DEV, that's for modders to do, and even they should have a good reason)

You should put user options into "Options.inc.h"... things which are either QoL, cosmetic or other optional features... which DON'T have any impact on game mechanics.
(anything that has impact on game mechanics is a modder option and should be put into the ruleset, NOT into user options)

If there is no better place in the ruleset, where you would put it.

As I see you exclude "all possibles", and now there is no place where add new configs :>
I think  your "Preferably never." refer to variables like `int Mod::DOOR_OPEN` not "variables" like `int _surrenderMode;` and I hope this second form is preferred by you.
This is correct?

[WarStalkeR]

Preferably never.
(but exceptions will always exist)

I assume you mean into "Options.inc.h".
(you should not put anything into "fixedUserOptions" as a DEV, that's for modders to do, and even they should have a good reason)

You should put user options into "Options.inc.h"... things which are either QoL, cosmetic or other optional features... which DON'T have any impact on game mechanics.
(anything that has impact on game mechanics is a modder option and should be put into the ruleset, NOT into user options)

If there is no better place in the ruleset, where you would put it.

Got it.

I initially perceived it like this:
1) Variables in `Mod.cpp/h` that are called via `_game->getMod()->getVariableValue()` are for some massive core features that enable/disable whole subset of other features.
2) Variables in `Options.cpp/inc.h` that are called via `Options::VARIABLE_NAME` are as you said some QoL features that don't affect game mechanics itself and intended to be configurable via options.cfg file.
3) Variables in `constants` that are called via `Mod::VARIABLE_NAME` for various features that are intended to be alterable only though .rul files. Such as when option is directly tied to localization for example (column offset for example).

[Meridian]

As I see you exclude "all possibles", and now there is no place where add new configs :>

Of course I don't want to exclude all possibilities

He asked a generic question, so I gave a generic answer.

But let's make at least one example:
What I mean by "preferably never" is that we should try to avoid "standalone top-level" parameters and try to at least group them together per feature or feature set, or category, or whatever else that makes sense.

Bad example (7 standalone parameters):

Code: [Select]

manaEnabled: false
manaBattleUI: false
manaUnlockResearch: STR_SORCERY     # empty by default
manaTrainingPrimary: false
manaTrainingSecondary: false
manaWoundThreshold: 200             # default is 200
manaReplenishAfterMission: true

Good/better example (1 parameter group):

Code: [Select]

mana:
  enabled: false
  battleUI: false
  unlockResearch: STR_SORCERY     # empty by default
  trainingPrimary: false
  trainingSecondary: false
  woundThreshold: 200             # default is 200
  replenishAfterMission: true


I think  your "Preferably never." refer to variables like `int Mod::DOOR_OPEN` not "variables" like `int _surrenderMode;` and I hope this second form is preferred by you.
This is correct?

Yes, second form is generally preferred.

But as I said above, please try to not create "too many" top-level YAML nodes.
I am guilty of creating too many myself in the earlier days, and I hate myself for it now... many of these global variables could have been grouped together nicely (e.g. https://www.ufopaedia.org/index.php/Ruleset_Reference_Nightly_(OpenXcom)#Basescape.2FPersonnel ).
And changing them now is not possible, because literally every mod uses them and I cannot break backwards compatibility.

[Meridian]

PS: the first form I used mostly in places like TileEngine.cpp, simply because it didn't/doesn't have access to Mod object.

[WarStalkeR]

Now it is clear, when cases #1, #2 and #3 are used. This explains pretty much everything.

Now I'm off to do some little more code refactoring.

Thank you very much Yankes and Meridian!