Documentation for settings.cfg

[corycohen]

I'm opening this conversation here to provide a better forum for discussing proposed updates to the documentation for the settings.cfg file. Following comments on a recent pull request I've decide to update the Wiki page: https://wiki.openmw.org/index.php?title ... ile_tweaks

This forum will provide a place to discuss that update, the settings themselves, and some questions I have about how their intended behavior. For example, I wrote:

> I think there's a bug in the way that always run is updated in the config file.

And Scrawl responded:

> In what way? Code looks ok to me.

In my opinion, the "always run" setting is an expression of whether the player wants to be running by default. The current implementation instead remembers whether the player was running (using CapsLock) at the time that they last exited OpenMW. There are many situations in which you might exit with CapsLock in a different state, and not want to change the "default" behavior.

Personally, I use the CapsLock key fairly frequently to toggle "always run" during a particular session of game play, but I would like for the CapsLock light to consistently indicate whether I'm running or not. Instead, the observed behavior is that 50% of the time I exit with CapsLock reversed from the position that it started in, and thus change the default setting for the next session.

So, I guess what I'm saying is that I believe that the option should be toggled in the Options panel (or the config file) and that the Caps Lock key should be a completely independent variable that controls running for the current execution of OpenMW. I suspect that at the implementation level that these two mode have been co-mingled, producing what I consider to be a bug.

Please discuss.

[corycohen]

Emperor Arthur wrote (in the git hub pull-request thread):

If you have information in the wiki that's not in the file the link to the wiki needs to be extremely obvious.

My intention was to begin the settings.cfg with a preamble that explained that the Wiki has more complete documentation for the file. Then probably the wanring about the overwrites, and maybe little else...

Also, if yo do smaller comments, I'd really appreciate it if each had the minimum and maximum values in there.

Agreed. Part of what started me down this path was that I had no idea what the scale or valid ranges for any of the options were. But with more complete documentation on the wiki, I can probably get by with something like "[-100 to 100]" in the settings.cfg now. I'll also rely on the presence of a decimal point to distinguish integers from floating point values, and the other types are fairly self evident, but with no other documentation I wouldn't have wanted to rely on that.

[corycohen]

Scrawl wrote (in the git-hub pull request thread) regarding the "ui sensitivity" setting:

This setting is no longer used because we're using hardware cursor movement. I must have forgotten to remove it when hardware cursors were implemented.

With hardware cursors, the only way to control the cursor's sensitivity is via the operating system's mouse settings. Having the game access and change the operating system settings would be a) complicated to implement and b) potentially inadvisable since we'd be left with the application specified settings if the application crashed.

Removed in master.

I suspected something like that. Determining this experimentally required a few restarts of OpenMW, and is just the kind of issue that prompted me to try and document the options more comprehensively. It's never quite clear whether a setting is really disabled, or if you're just doing it wrong. Witness my confusion over the companion window. I'll watch for the commit and update the documentation on the wiki appropriately.

I had a bunch of settings in my settings.cfg that were from earlier versions of OpenMW. Perhaps we should consider removing former settings from the config file to improve clarity for files that are upgraded. I believe that the current behavior is to keep unrecognized options. I've also made a map of which values are only retrieved by the game code, and which are also set.

Finally, there's some interesting inconsistencies between which settings can be configured where (e.g. settings.cfg file only, Options GUI, and OpenMW Launcher). I tried to document that in the proposed settings file but it's more appropriate for that to be in the Wiki in my opinion. I know that some of those choices are limited to one place or another (e.g. Screen #), but some omissions look like just that -- accidental omissions. I'll try to inventory those an present a consistent review.

[scrawl]

In my opinion, the "always run" setting is an expression of whether the player wants to be running by default. The current implementation instead remembers whether the player was running (using CapsLock) at the time that they last exited OpenMW. There are many situations in which you might exit with CapsLock in a different state, and not want to change the "default" behavior.

Upon restarting, you get the same run state that you exited with. Isn't that the logical thing to do? I don't see much of a point in changes here.

Personally, I use the CapsLock key fairly frequently to toggle "always run" during a particular session of game play, but I would like for the CapsLock light to consistently indicate whether I'm running or not. Instead, the observed behavior is that 50% of the time I exit with CapsLock reversed from the position that it started in, and thus change the default setting for the next session.

The state of caps lock LED is not currently tracked or acted upon. You can bind the run toggle to other keys than caps lock (which I would personally recommend - using the caps lock key messes with text entry). That said, I guess it's a valid feature request.

I had a bunch of settings in my settings.cfg that were from earlier versions of OpenMW. Perhaps we should consider removing former settings from the config file to improve clarity for files that are upgraded. I believe that the current behavior is to keep unrecognized options.

Correct. We keep obsoleted settings in case the user wants to revert to an earlier version of OpenMW for whatever reason. Unfortunately, this could result in users accidentally changing the obsoleted setting instead of the current one and then wonder why changes are not applied (I have done that on a few occasions). I guess it makes sense to remove obsoleted settings on load. Or at least put an # Obsoleted comment above.

[corycohen]

In the pull request for the settings change, Scrawl wrote:

Would it make sense to put this next to the 'contrast' option as it used to? These two options are kind of related.

I agree. But the settings.cfg file exporter seems to disagree with both of us. It always writes all options and sections in alphabetical order. I reordered the options in the default settings.cfg to match that order thinking that users would find it easier to update their configuration if the options were in the same order.

I think that the current approach has several problems:

• Relevant options are not adjacent to each other.
• Important options are not first within a section. e.g. The option that enables or disables the entire section is not first.
• There's no way to maintain the nice new default comments that we're developing in the user settings.cfg file that actually matters (the user settings.cfg).
• Rewriting the user file discards all user generated comments, which is kind of rude.
• There's no ability to comment out or annotate disabled or deprecated options during rewrite.

I recently committed some proposed changes to alter the behavior of Settings::Manager::saveUser() that addresses most of these issues. The biggest problem with the proposed code is that it interacts poorly openmw-launcher, which has it's own Qt-based version of the same code I was replacing. :-* The end result is that if you run openmw-launcher, it tramples the config before my new code gets a chance to preserve anything.

I wanted to show what I had done so far before proceeding any further, but my recommendation is to alter component/settings/settingbase.hpp and apps/launcher/settings/graphicsettings.cpp to use the same infrastructure that the OpenMW Game engine uses (which is also a component), and then convert the std::strings and std:maps into QMap and QStrings, so that the same Qt friendly API can be used. There's a small bit of drama involving passing a stream handle instead of a filename, but I can cope with that.

Further there's some follow on change that could be made, such as better comments for newly added settings and deprecated options, but again -- no more than 2-3 changes at a time.

[corycohen]

Upon restarting, you get the same run state that you exited with. Isn't that the logical thing to do? I don't see much of a point in changes here.

It would be if exiting implied that I really wanted to change my "default" behavior. Practically all other settings reflect _intentional_ changes so it's a little hard to see how this one is different, but perhaps think about how running relates to sneaking, and why we don't have an "always sneak" option. We already have a "toggle run" option -- it's always true and bound to CapsLock. Would we save whether you were sneaking to the settings file based on whether you were sneaking when you last exited?

The state of caps lock LED is not currently tracked or acted upon.

I didn't really mean to draw so much attention to the LED, except in that one session it means I'm running, and in the next it means I'm not. I'd like it to at least mean the same thing every time.

You can bind the run toggle to other keys than caps lock (which I would personally recommend - using the caps lock key messes with text entry).

Fair point. I probably should change that binding, because I do have that problem.

That said, I guess it's a valid feature request.

I'd prefer to convince you, but I'll take whatever I can get. It's not that big of a deal.

We keep obsoleted settings in case the user wants to revert to an earlier version of OpenMW for whatever reason.

Thinking about this comment influenced my recent commit. We're now very close to being able to create a little data structure that describes settings (both current and deprecated) in a way that controls how the file is updated. In particular, imagine that the CategorySettingStatusMap which currently contains booleans recording whether the setting has been written to the file yet, was instead replaced with a SettingDescriptionStructure that included important information like it's deprecation status, a one or two line comment, etc. If that data structure was hard coded, passed in, read from some other config file or whatever, I'd have the information needed to do more sophisticated updates. For example, we could replace the generic comments added to the settings file when new settings spring into existence with setting specific "brief" summaries unique to each setting, and also record why settings were deprecated, etc.

[corycohen]

A couple of things people might want to try/test:

• Start OpenMW, and replace the user settings.cfg with the settings-default.cfg while running. On exit, your settings should be saved, but in the new order, and with the default comments.
• Start OpenMW normally, don't change anything, and observe that the settings.cfg file is not re-written at all on exit. If the launcher stopped trampling the settings.cfg you could tell when you last changed your settings.
• Start OpenMW and change some settings in the Options menu. Observe that the changes are reported to the console on exit. Good for awareness of new options?
• Remove some options entirely from the settings.cfg to simulate an upgrade from an old config. Notice that the options are added in the appropriate section (or the case of an entirely new section, at the end). Too bad that they don't have descriptive comments...

Be sure to invoke OpenMW directly until we decide what to do with the launcher...

I think it would be good to somehow mark deprecated settings, but I have no list of deprecated settings to refer to in the code. Further the existing infrastructure seems to explicitly pass them through even if they're invalid. I suppose that this is a "good thing" if you want to run multiple versions of OpenMW against the same settings.cfg file. On the other hand, letting them accumulate indefinitely with no comments isn't very helpful either. Are there opinions on what should or should not be done here?

Another question I have is: How strict do we really want to be? Playing fast and loose on deprecated options doesn't really seem consistent with the assert style exits we currently have for failing to find an option in the settings.cfg, or a completely missing settings.cfg. I think that in both cases, we should continue to run, but with a default value. Where would those values come from? I assume settings-default.cfg. What if there was a value but it was known to causes crashes? Again, I think going with a valid default and warning is more appropriate than asserting.

[corycohen]

One more post, and I'll shut up for a while. I promise.

This one documents my current thinking about the "brief" comments in the setting.cfg file, versus the more complete documentation on the Wiki. I need a set of rules to guide that process I'll get confused about what goes where and why. I also want others in the community to have a say before I write tons of text that has to be reworked. For example, in the GitHub pull request trhead:

I'd really appreciate it if each had the minimum and maximum values in there.

Which I've done for recommended values, but not hard limits. Please let me know if you think the updated version is ok.

I tried to constrain myself to one line (or sometimes two) for each setting. Why? Because it's a slippery slope to reproducing the Wiki documentation in the config file, and we concluded that the config file should be reminders and hints for experts, and the Wiki is for more detailed documentation for all users.

I used as much of the line as possible, because there's no point in wasting it. The first goal was a brief description. The second goal was information about recommended values, including explanations when possible in a line or two. These were generally inside parentheses. The third goal was warnings and cautions about the setting that might prompt the user to read the detailed documentation. The fourth goal was to indicate when an option was disabled or unused.

I did not specify the type of the setting, which should be obvious from the value, nor did I specify the default value. At the time, the comments could only be in the settings-default.cfg file, so I didn't see much point in that. Now that the comments could appear in the user's settings.cfg, that decision is a little less clear but I'm still inclined to leave defaults to the wiki.

I did not try to explain the effects of the values if it should be obvious to an expert (e.g. higher resolution results in better quality), although I sometimes commented on this when space was sufficient. I used phrases and not proper grammatical sentences to shorten the text.

I did not try to communicate absolute limits on values, but rather suggested values. These values are inherently subjective, but are also the most useful for understanding which values are appropriate. The detailed documentation can discuss the implications of values outside the recommended range but in the technically permissible range. I also avoided providing advice, which I belive explicitly belongs in the documentation where the pros and cons can be discussed in more detail. The problem (in my opinion) with reporting hard limits in settings.cfg is there's often a larger story about why that's possible, but not recommended.

Opinions and feedback welcomed...

[sjek]

for ease the navigation there's the original raft
https://github.com/cfcohen/openmw/commi ... 1fcd37c377

which has been revised to shorter version here
https://github.com/OpenMW/openmw/pull/819/files

i think one way to solve this would be to include full documentation with the distribution or a way for it, for future rewrites by third parties and / or making it's own page to wiki and linking to config files tweaks page as that's a lot of text to read but as said handy for new users or just casual gamers. there's anyway some parts in the wiki which are in need for revising in 1.0

and while technical in nature in descripting options, there's not so much possibility for update need besides when new features are added.

How strict do we really want to be? Playing fast and loose on deprecated options doesn't really seem consistent with the assert style exits we currently have for failing to find an option in the settings.cfg, or a completely missing settings.cfg.

i think it's rare to offer file that can be modified to modify already modified values but nice addition. anyhow doing this in settings-default.cfg or settings.cfg is confusing as it's grown to it's more logical one dafaults taken from settings-default if the settings.cfg file is missing and in the meantime left those conflicts, maybe doc...
good test options

making one more file could solve also this althought little bit code duplication.
later if modders want to change defaults or settings.cfg it could be added as a file chooser into launcher or openmw.cfg depending on later development respectively. making the reading ability needed.

post 1.0 there's possibly, dealing with used fallback values from openmw.cfg <- morrowind.ini

don't know how much gain there would be for two separate read / write lines as a debug feature

for debrecated options some can be used in some time again

Spoiler: Show

missing options:
[General]
contrast (moved to video)
gamma
num mipmaps
shader mode

(texture filtering is written if trilinear is chosen instead of default bilinear)

[HUD]
fps

[Objects]
num lights
use static geometry

[Video]
opengl rtt mode
render system

Code: Select all

[Viewing distance]
fog end factor = 1.0
fog start factor = 0.5
limit small object distance = false
small object distance = 3500
small object size = 250
viewing distance = 4600

replaced with [Camera]: (viewing distance and small feature culling) and fog read from openmw.cfg fallback values i think like with underwater fog

at least somekind of ability to differ between lines is needed for which that reading them little haywire is used for bypass the need to update it when changes are made.

comments out and otherwise searching written values? ideas for workaround?

[corycohen]

There's a draft now of the Wiki formatted settings.cfg documentation at:

https://wiki.openmw.org/index.php?title=Settings

I'm probably not completely done because I'd like to add some screen shots of selected settings, and I'm still adding links to educational material about the purpose of the setting.

Comments, feedback and changes are welcomed. If there are typos or inaccuracies, please just fix them since it'll probably be less typing for all of us.