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.

Example

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

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 default
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 root_config_file(&self) -> &Path

Path to the configuration file which is the root of the configuration chain 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 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 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 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) -> OpenMWConfiguration

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() -> OpenMWConfiguration

Returns the “default value” for a type.

impl Display for OpenMWConfiguration

Keep in mind this is not meant to be used as a mechanism to write the openmw.cfg contents. Since the openmw.cfg is a merged entity, it is impossible to distinguish the origin of one particular data directory Or content file once it has been applied - this is doubly true for entries which may only exist once in openmw.cfg. Thus, what this method provides is the composite configuration.

It may be safely used to write an openmw.cfg as all directories will be absolutized upon loading the config.

Token information is also lost when a config file is processed. It is not necessarily recommended to write a configuration file which loads other ones or uses tokens for this reason.

Comments are also preserved.

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

Formats the value using the given formatter.