Struct OpenMWConfiguration 

pub struct OpenMWConfiguration { /* private fields */ }

A fully-resolved OpenMW configuration chain.

Constructed by walking the config= chain starting from a root openmw.cfg, accumulating every setting from every file into a flat list. The list preserves source attribution and comments so that save_user can write back only the user-owned entries, and Display can reproduce a valid, comment-preserving openmw.cfg.

Implementations

impl OpenMWConfiguration

pub fn from_env() -> Result<Self, ConfigError>

Errors

Returns ConfigError if the path from the environment variable is invalid or if config loading fails.

Discovery order matches OpenMW root config startup semantics:

1. OPENMW_CONFIG, an explicit openmw.cfg file path.
2. OPENMW_CONFIG_DIR, a path list of directories containing openmw.cfg.
3. Executable-adjacent openmw.cfg.
4. Platform global config openmw.cfg.

This deliberately does not fall back to Self::new(None). User config is loaded only if the discovered root config references it, usually through config="?userconfig?".

Example

use openmw_config::OpenMWConfiguration;
let config = OpenMWConfiguration::from_env()?;

pub fn from_env_or_user_config() -> Result<Self, ConfigError>

Loads an OpenMW configuration using environment/root discovery with a user-config fallback.

This is the discovery mode external tools normally want:

1. Honor Self::from_env semantics, including OPENMW_CONFIG, OPENMW_CONFIG_DIR, executable-adjacent root config, and platform global root config.
2. If strict root discovery finds no root config, fall back to the default user openmw.cfg (?userconfig?/openmw.cfg).

Explicit environment errors are still errors. This method only adds a fallback for the “no local/global root config exists” case.

Errors

Returns ConfigError if config loading fails or if no root/user config exists.

pub fn new(path: Option<PathBuf>) -> Result<Self, ConfigError>

Errors

Returns ConfigError if the path does not exist, is not a valid config, or if loading the config chain fails.

Example

use std::path::PathBuf;
use openmw_config::OpenMWConfiguration;

// Platform/user config default (?userconfig?/openmw.cfg), not OpenMW root discovery.
let config = OpenMWConfiguration::new(None)?;

// Specific directory or file path — both are accepted
let config = OpenMWConfiguration::new(Some(PathBuf::from("/home/user/.config/openmw")))?;

pub fn new_empty( user_config_dir: impl Into<PathBuf>, ) -> Result<Self, ConfigError>

Creates an empty configuration rooted at user_config_dir without reading from disk.

The argument is a configuration directory, not an openmw.cfg file path. New settings are attributed to user_config_dir/openmw.cfg, and save/export APIs treat that file as the user config. The directory and file do not need to exist yet.

Errors

Returns ConfigError::NotFileOrDirectory if user_config_dir is empty or is shaped like an openmw.cfg file path. This keeps the directory-level API honest for future config-family files such as settings.cfg and shaders.yaml.

pub fn load_optional(path: impl Into<PathBuf>) -> Result<Self, ConfigError>

Loads a configuration if it exists, otherwise creates an empty configuration at the same config context.

Existing paths behave exactly like Self::new. A missing openmw.cfg file path starts an empty config from its parent directory; a missing directory path starts an empty config from that directory. No input file is created unless a later save call writes one.

Errors

Returns ConfigError for empty paths, invalid existing inputs, or load failures from existing configs.

pub fn root_config_file(&self) -> &Path

Path to the configuration file which is the root of the configuration chain For Self::from_env, this is the root discovered by OpenMW startup semantics: explicit environment override, executable-adjacent openmw.cfg, or platform global config. It is not necessarily the user config; package installs usually load the user config through a root config="?userconfig?" entry.

Typically, this will be whatever is defined in the Paths documentation for the appropriate platform: https://openmw.readthedocs.io/en/latest/reference/modding/paths.html#configuration-files-and-log-files

pub fn root_config_dir(&self) -> PathBuf

Same as root_config_file, but returns the directory it’s in. Useful for reading other configuration files, or if assuming openmw.cfg Is always called openmw.cfg (which it should be)

Panics

Panics if the root config path has no parent directory (i.e. it is a filesystem root).

pub fn is_user_config(&self) -> bool

pub fn user_config(self) -> Result<Self, ConfigError>

Errors

Returns ConfigError if the user config path cannot be loaded.

pub fn user_config_ref(&self) -> Result<Self, ConfigError>

Errors

Returns ConfigError if the user config path cannot be loaded.

pub fn user_config_path(&self) -> PathBuf

In order of priority, the list of all openmw.cfg files which were loaded by the configuration chain after the root. If the root openmw.cfg is different than the user one, this list will contain the user openmw.cfg as its last element. If the root and user openmw.cfg are the same, then this list will be empty and the root config should be considered the user config. Otherwise, if one wishes to get the contents of the user configuration specifically, construct a new OpenMWConfiguration from the last sub_config.

Openmw.cfg files are added in declaration order, traversing the config= chain level-by-level. In a branching chain, sibling config= entries are processed before grandchildren. If replace=config appears in a file, any earlier settings and config= entries from that same parse scope are discarded before continuing, matching OpenMW’s reset semantics. The highest-priority openmw.cfg loaded (the last one!) is considered the user openmw.cfg, and will be the one which is modifiable by OpenMW-Launcher and OpenMW proper.

See https://openmw.readthedocs.io/en/latest/reference/modding/paths.html#configuration-sources for examples and further explanation of multiple config sources.

Path to the highest-level configuration directory

pub fn userdata(&self) -> Option<&DirectorySetting>

pub fn set_userdata(&mut self, new: Option<DirectorySetting>)

pub fn resources(&self) -> Option<&DirectorySetting>

pub fn set_resources(&mut self, new: Option<DirectorySetting>)

pub fn data_local(&self) -> Option<&DirectorySetting>

pub fn set_data_local(&mut self, new: Option<DirectorySetting>)

pub fn encoding(&self) -> Option<&EncodingSetting>

pub fn set_encoding(&mut self, new: Option<EncodingSetting>)

pub fn set_data_local_path(&mut self, path: impl AsRef<Path>)

Replaces the singleton data-local= directory with a path attributed to the user config.

The value is parsed through DirectorySetting so quote, token, and relative-path handling remains centralized.

pub fn set_resources_path(&mut self, path: impl AsRef<Path>)

Replaces the singleton resources= directory with a path attributed to the user config.

The value is parsed through DirectorySetting so quote, token, and relative-path handling remains centralized.

pub fn set_user_data_path(&mut self, path: impl AsRef<Path>)

Replaces the singleton user-data= directory with a path attributed to the user config.

The cfg key is user-data; ?userdata? is only a token. There is no userdata= key here.

pub fn clear_data_local(&mut self)

Clears the singleton data-local= directory setting.

pub fn clear_resources(&mut self)

Clears the singleton resources= directory setting.

pub fn clear_user_data(&mut self)

Clears the singleton user-data= directory setting.

pub fn content_files_iter(&self) -> impl Iterator<Item = &FileSetting>

Content files are the actual mods or plugins which are created by either OpenCS or Bethesda’s construction set These entries only refer to the names and ordering of content files. vfstool-lib should be used to derive paths

pub fn has_content_file(&self, file_name: &str) -> bool

Returns true if the named plugin is present in the content= list.

pub fn has_groundcover_file(&self, file_name: &str) -> bool

Returns true if the named plugin is present in the groundcover= list.

pub fn has_archive_file(&self, file_name: &str) -> bool

Returns true if the named archive is present in the fallback-archive= list.

pub fn has_data_dir(&self, file_name: &str) -> bool

Returns true if the given path is present in the data= list.

Both / and \ are normalised to the platform separator before comparison, so the query does not need to use a specific separator style.

pub fn add_content_file( &mut self, content_file: &str, ) -> Result<(), ConfigError>

Errors

Returns ConfigError::CannotAddContentFile if the file is already present in the config.

pub fn groundcover_iter(&self) -> impl Iterator<Item = &FileSetting>

Iterates all groundcover= entries in definition order.

pub fn add_groundcover_file( &mut self, content_file: &str, ) -> Result<(), ConfigError>

Errors

Returns ConfigError::CannotAddGroundcoverFile if the file is already present in the config.

pub fn remove_content_file(&mut self, file_name: &str)

Removes all content= entries matching file_name.

pub fn remove_groundcover_file(&mut self, file_name: &str)

Removes all groundcover= entries matching file_name.

pub fn remove_archive_file(&mut self, file_name: &str)

Removes all fallback-archive= entries matching file_name.

pub fn remove_data_directory(&mut self, data_dir: &PathBuf)

Removes any data= entry whose resolved path or original string matches data_dir.

pub fn add_data_directory(&mut self, dir: &Path)

Appends a data directory entry attributed to the user config. Does not check for duplicates.

pub fn add_archive_file( &mut self, archive_file: &str, ) -> Result<(), ConfigError>

Errors

Returns ConfigError::CannotAddArchiveFile if the archive is already present in the config.

pub fn fallback_archives_iter(&self) -> impl Iterator<Item = &FileSetting>

Iterates all fallback-archive= entries in definition order.

pub fn set_content_files(&mut self, plugins: Option<Vec<String>>)

Replaces all content= entries with plugins, or clears them if None.

Entries are attributed to the user config path. No duplicate checking is performed.

pub fn set_fallback_archives(&mut self, archives: Option<Vec<String>>)

Replaces all fallback-archive= entries with archives, or clears them if None.

Entries are attributed to the user config path. No duplicate checking is performed.

pub fn generic_settings_iter(&self) -> impl Iterator<Item = &GenericSetting>

Iterates all preserved generic key=value entries in definition order.

pub fn set_generic_settings(&mut self, key: &str, values: Option<Vec<String>>)

Replaces all preserved generic key=value entries with values, or clears them if None.

Entries are attributed to the user config path. No duplicate checking is performed.

pub fn add_generic_setting(&mut self, key: &str, value: &str)

Appends a preserved generic key=value entry attributed to the user config.

pub fn settings_matching<'a, P>( &'a self, predicate: P, ) -> impl Iterator<Item = &'a SettingValue>

where P: Fn(&SettingValue) -> bool + 'a,

Iterates all settings for which predicate returns true.

pub fn clear_matching<P>(&mut self, predicate: P)

where P: Fn(&SettingValue) -> bool,

Removes all settings for which predicate returns true.

pub fn set_data_directories(&mut self, dirs: Option<Vec<PathBuf>>)

Replaces all data= entries with dirs, or clears them if None.

Entries are attributed to the user config path. No duplicate checking is performed.

pub fn set_game_setting( &mut self, base_value: &str, config_path: Option<PathBuf>, comment: &mut String, ) -> Result<(), ConfigError>

Given a string resembling a fallback= entry’s value, as it would exist in openmw.cfg, Add it to the settings map. This process must be non-destructive

Errors

Returns ConfigError if base_value cannot be parsed as a valid game setting.

pub fn set_game_settings( &mut self, settings: Option<Vec<String>>, ) -> Result<(), ConfigError>

Replaces all fallback= entries with settings, or clears them if None.

Each string must be in Key,Value format — the same as it would appear after the = in an openmw.cfg fallback= line.

Errors

Returns ConfigError if any entry in settings cannot be parsed as a valid game setting.

pub fn sub_configs(&self) -> impl Iterator<Item = &DirectorySetting>

Iterates all config= sub-configuration entries in effective definition order.

replace=config clears prior config= entries in the current parse scope, so this iterator only exposes sub-configurations that remain in the effective chain.

pub fn config_chain(&self) -> impl Iterator<Item = &ConfigChainEntry>

Returns the observed configuration-chain traversal in parser order.

Includes successfully loaded config files and config= targets that were skipped because no openmw.cfg exists in that directory.

pub fn game_settings(&self) -> impl Iterator<Item = &GameSettingType>

Fallback entries are k/v pairs baked into the value side of k/v pairs in fallback= entries of openmw.cfg. They are used to express settings which are defined in Morrowind.ini for things such as: weather, lighting behaviors, UI colors, and levelup messages.

Returns each key exactly once — when a key appears multiple times in the config chain, the last-defined value wins.

Example

use openmw_config::OpenMWConfiguration;
let config = OpenMWConfiguration::new(None)?;
for setting in config.game_settings() {
    println!("{}={}", setting.key(), setting.value());
}

pub fn get_game_setting(&self, key: &str) -> Option<&GameSettingType>

Retrieves a gamesetting according to its name. This would be whatever text comes after the equals sign = and before the first comma , Case-sensitive!

pub fn data_directories_iter(&self) -> impl Iterator<Item = &DirectorySetting>

Data directories are the bulk of an OpenMW Configuration’s contents, Composing the list of files from which a VFS is constructed. For a VFS implementation, see: https://github.com/magicaldave/vfstool/tree/main/vfstool_lib

Calling this function will give the post-parsed versions of directories defined by an openmw.cfg, So the real ones may easily be iterated and loaded. There is not actually validation anywhere in the crate that DirectorySettings refer to a directory which actually exists. This is according to the openmw.cfg specification and doesn’t technically break anything but should be considered when using these paths.

pub fn to_resolved_string(&self) -> String

Serializes the fully-composed configuration as a relocated, flattened openmw.cfg.

Directory-valued settings (data=, data-local=, resources=, and user-data=) are emitted from their resolved paths, not their original token or relative spelling. Chain control entries such as config= and replace= are excluded because this output is already the composed result; reloading the chain from the flattened file would be doing the work twice, and probably differently. Synthetic data-local-as-data entries are also omitted.

Use the Display implementation for preservation-oriented serialization instead.

pub fn save_to_path(&self, path: impl AsRef<Path>) -> Result<(), ConfigError>

Writes the full composite configuration to an arbitrary path.

This is intended for importer-style output where the exact destination is supplied by the caller rather than inferred from the loaded config chain.

Errors

Returns ConfigError::NotWritable if the destination directory is not writable. Returns ConfigError::Io if writing the file fails.

pub fn save_resolved_to_path( &self, path: impl AsRef<Path>, ) -> Result<(), ConfigError>

Writes Self::to_resolved_string to an arbitrary path using atomic replace semantics.

This is the relocation-safe export API for importers and preview/output tools. It omits config= and replace= chain-control entries and writes directory-valued settings using resolved paths so moving the output file does not change what those paths mean.

Errors

Returns ConfigError::NotWritable if the destination directory is not writable. Returns ConfigError::Io if writing the file fails.

pub fn save_user(&self) -> Result<(), ConfigError>

Saves the currently-defined user openmw.cfg configuration.

Only settings whose source is the user config file are written; settings inherited from parent configs are not affected. Modifications applied to inherited settings at runtime are therefore not persisted by this method.

Errors

Returns ConfigError::NotWritable if the target path is not writable. Returns ConfigError::Io if writing the file fails.

pub fn save_subconfig(&self, target_dir: &Path) -> Result<(), ConfigError>

Saves the openmw.cfg belonging to a loaded sub-configuration.

target_dir must be the directory of a config= entry already present in the loaded chain. This method refuses to write to arbitrary paths to prevent accidental overwrites.

Errors

Returns ConfigError::SubconfigNotLoaded if target_dir is not part of the chain. Returns ConfigError::NotWritable if the target path is not writable. Returns ConfigError::Io if writing the file fails.

Trait Implementations

impl Clone for OpenMWConfiguration

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OpenMWConfiguration

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OpenMWConfiguration

fn default() -> Self

Returns the “default value” for a type.

impl Display for OpenMWConfiguration

Preservation-oriented openmw.cfg serialization for the composed configuration.

Directory-valued settings use their original text so user-authored relative paths, tokens, and quoting survive round-trips. That makes this suitable for preservation-style output and for the internals of OpenMWConfiguration::save_user / OpenMWConfiguration::save_subconfig. It is not relocation-safe flattened export: writing this string to a different directory can change the meaning of relative paths. Use OpenMWConfiguration::to_resolved_string or OpenMWConfiguration::save_resolved_to_path for importer/export output.

Synthetic data-local-as-data entries are omitted. Comments are preserved.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.