openmw-config-1.0.0 has been yanked.

openmw_config

openmw_config is a lightweight Rust crate that provides a simple, idiomatic API for reading, composing, and writing OpenMW configuration files. It closely matches OpenMW's own configuration parser, supporting configuration chains, directory tokens, and value replacement semantics. For comprehensive VFS coverage, combine with vfstool_lib.

Why Use It
Features
Rust Quick Start
Lua Quick Start
Rust Usage
Lua Bindings (mlua)
Advanced Behavior
Quality & Testing
Manual Diagnostics
Compatibility Guarantees
Known Limitations

Why Use It

OpenMW-accurate semantics - models config= traversal, replace=* behavior, and token expansion (?local?, ?global?, ?userdata?, ?userconfig?) to match real parser behavior.
Safe persistence model - save_user() and save_subconfig() use atomic write semantics to avoid partial writes.
Integration-friendly API - ergonomic Rust API plus embedded Lua host bindings via mlua, with a camelCase-only Lua surface.
Diagnostics and predictability - line-aware parse errors, explicit chain introspection, and deterministic roundtrip serialization.

Features

Accurate parsing - mirrors OpenMW's config resolution, including config=, replace=, and tokens like ?local?, ?global?, ?userdata?, and ?userconfig?.
Multi-file chains - multiple openmw.cfg files are merged according to OpenMW's rules; last-defined wins.
Round-trip serialization - Display on OpenMWConfiguration emits a valid openmw.cfg, preserving comments.
Dependency-light core - Unix/macOS path resolution and env expansion are implemented with std; Windows default paths use Known Folder APIs via windows-sys (Windows-only target dep). Lua support is optional via the lua feature.

Rust Quick Start

Load the active config chain, inspect values, mutate, and save in a few lines:

[dependencies]
openmw-config = "1"

use openmw_config::OpenMWConfiguration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load the default config chain for the current platform
    let config = OpenMWConfiguration::from_env()?;

    for plugin in config.content_files_iter() {
        println!("{}", plugin.value());
    }

    for dir in config.data_directories_iter() {
        println!("{}", dir.parsed().display());
    }

    // Mutate and persist to the user config with atomic write behavior
    let mut config = config;
    config.add_content_file("Extra.esp")?;
    config.save_user()?;

    Ok(())
}

See Rust Usage and API Overview for more patterns.

Lua Quick Start

Embed openmwConfig into a host-created Lua state:

[dependencies]
openmw-config = { version = "1", features = ["lua"] }
mlua = { version = "0.10", default-features = false, features = ["luajit52", "vendored"] }

use mlua::Lua;
use openmw_config::create_lua_module;

fn main() -> Result<(), mlua::Error> {
    let lua = Lua::new();
    let openmw = create_lua_module(&lua)?;
    lua.globals().set("openmwConfig", openmw)?;

    lua.load(r#"
      local cfg = openmwConfig.fromEnv()
      cfg:addContentFile("MyPlugin.esp")
      cfg:saveUser()
    "#).exec()?;

    Ok(())
}

This is embedded-host integration, not a standalone require("openmw_config") Lua module. See Lua Bindings (mlua) for the full Lua API surface.

Rust Usage

Loading a specific config

new() accepts either a directory containing openmw.cfg or a direct path to the file:

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

// From a directory
let config = OpenMWConfiguration::new(Some(PathBuf::from("/home/user/.config/openmw")))?;

// From a file path
let config = OpenMWConfiguration::new(Some(PathBuf::from("/home/user/.config/openmw/openmw.cfg")))?;
# Ok::<(), openmw_config::ConfigError>(())

Modifying and saving

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

let mut config = OpenMWConfiguration::new(None)?;

// Replace all content files
config.set_content_files(Some(vec!["MyMod.esp".into(), "Another.esp".into()]));

// Add a single plugin (errors if already present)
config.add_content_file("Extra.esp")?;

// Replace all data directories
config.set_data_directories(Some(vec![PathBuf::from("/path/to/Data Files")]));

// Replace all fallback archives
config.set_fallback_archives(Some(vec!["Morrowind.bsa".into()]));

// Write the user config back to disk
config.save_user()?;
# Ok::<(), Box<dyn std::error::Error>>(())

Serialization

OpenMWConfiguration implements Display, which produces a valid openmw.cfg string with comments preserved:

use openmw_config::OpenMWConfiguration;

let config = OpenMWConfiguration::new(None)?;
println!("{config}");
# Ok::<(), openmw_config::ConfigError>(())

API Overview

Core Rust API	Description
`OpenMWConfiguration::from_env()` / `OpenMWConfiguration::new(path)`	Load from env/defaults or explicit file/directory path
`root_config_file()` / `root_config_dir()`	Root config file and parent directory
`user_config_ref()` / `user_config_path()`	Resolve highest-priority user config
`sub_configs()` / `config_chain()`	Traverse effective subconfigs and parser-order chain events
`content_files_iter()` / `groundcover_iter()` / `fallback_archives_iter()`	Read loaded file collections
`data_directories_iter()` / `game_settings()` / `get_game_setting(key)`	Read resolved directories and `fallback=` settings
`add_` / `remove_` / `set_*` methods	Mutate loaded values
`save_user()` / `save_subconfig(path)`	Persist changes using atomic writes
`default_` and `try_default_` free functions	Resolve default config/user paths (panic or fallible variants)
`create_lua_module(lua)` (with `lua` feature)	Build a Lua table for embedded host integration

For the complete API surface (including helper structs and all methods), see docs.rs/openmw-config.

Task-oriented map:

Load config state - OpenMWConfiguration::from_env(), OpenMWConfiguration::new(path)
Inspect chain resolution - sub_configs(), config_chain(), user_config_path()
Edit plugin/data lists - add_*, remove_*, set_* method families
Read/write settings - game_settings(), get_game_setting(key), set_game_setting(...)
Persist safely - save_user(), save_subconfig(path)

Advanced Behavior

Config chains - sub_configs() walks the config= entries that were loaded. The last entry is the user config; everything above it is read-only from OpenMW's perspective.
Replace semantics - replace=content, replace=data, etc. are honoured during load, exactly as OpenMW handles them. replace=config resets earlier settings and queued config= entries from the same parse scope before continuing.
Token expansion - ?local?, ?global?, ?userdata?, and ?userconfig? in data= paths are expanded to platform-correct directories at load time.

Flatpak and token-resolution controls:

OPENMW_CONFIG_USING_FLATPAK - if set to any value, Flatpak path mode is enabled.
Auto-detection also enables Flatpak mode when FLATPAK_ID is set or /.flatpak-info exists.
OPENMW_FLATPAK_ID - optional app-id override (falls back to FLATPAK_ID, then org.openmw.OpenMW).
OPENMW_GLOBAL_PATH - optional override for the ?global? token target.
In Flatpak mode, ?userconfig? and ?userdata? resolve to ~/.var/app/<app-id>/config/openmw and ~/.var/app/<app-id>/data/openmw respectively.

config_chain() provides parser-order traversal details, including skipped missing subconfigs:

use openmw_config::{ConfigChainStatus, OpenMWConfiguration};

let config = OpenMWConfiguration::new(None)?;

for entry in config.config_chain() {
    let status = match entry.status() {
        ConfigChainStatus::Loaded => "loaded",
        ConfigChainStatus::SkippedMissing => "skipped-missing",
    };
    println!("[{status}] depth={} {}", entry.depth(), entry.path().display());
}
# Ok::<(), openmw_config::ConfigError>(())

Lua Bindings (`mlua`)

Public Lua methods/functions are intentionally camelCase only.
lua feature: embeds vendored LuaJIT with 5.2 compatibility (luajit52 + vendored).

Module exports (openmwConfig):

Lua function	Returns	Notes
`fromEnv()`	`config` userdata	Loads using `OPENMW_CONFIG` / `OPENMW_CONFIG_DIR` semantics
`new(pathOrNil)`	`config` userdata	`pathOrNil` may be file path, dir path, or `nil`
`defaultConfigPath()`	`string`	Platform default config dir
`defaultUserDataPath()`	`string`	Platform default userdata dir
`defaultDataLocalPath()`	`string`	Platform default data-local dir
`defaultLocalPath()`	`string`	Path backing the `?local?` token
`defaultGlobalPath()`	`string`	Path backing the `?global?` token (throws on unsupported platforms)
`tryDefaultConfigPath()`	`(string	nil, string
`tryDefaultUserDataPath()`	`(string	nil, string
`tryDefaultLocalPath()`	`(string	nil, string
`tryDefaultGlobalPath()`	`(string	nil, string
`version`	`string` field	Crate version string

config userdata methods:

Lua method	Returns	Notes
`rootConfigFile()` / `rootConfigDir()`	`string`	Resolved root file/path
`isUserConfig()`	`boolean`	Whether root is already highest-priority config
`userConfigPath()`	`string`	Highest-priority config directory
`userConfig()`	`config` userdata	Returns a user-config-focused clone
`toString()`	`string`	Serialized `openmw.cfg` output
`subConfigs()`	`string[]`	Effective loaded `config=` directories
`configChain()`	`table[]`	Rows: `{ path, depth, status }`, status is `loaded` or `skippedMissing`
`contentFiles()` / `groundcoverFiles()` / `fallbackArchives()`	`string[]`	Collection snapshots
`dataDirectories()`	`string[]`	Resolved `data=` directories
`gameSettings()`	`table[]`	Rows: `{ key, value, kind }`
`getGameSetting(key)`	`table	nil`
`userData()` / `resources()` / `dataLocal()` / `encoding()`	`string	nil`
`hasContentFile(name)` / `hasGroundcoverFile(name)` / `hasArchiveFile(name)` / `hasDataDir(path)`	`boolean`	Presence checks
`addContentFile(name)` / `addGroundcoverFile(name)` / `addArchiveFile(name)` / `addDataDirectory(path)`	`nil`	Mutating append operations
`removeContentFile(name)` / `removeGroundcoverFile(name)` / `removeArchiveFile(name)` / `removeDataDirectory(path)`	`nil`	Mutating remove operations
`setContentFiles(listOrNil)` / `setFallbackArchives(listOrNil)` / `setDataDirectories(listOrNil)`	`nil`	Replaces full collection, `nil` clears
`setGameSetting(value, sourcePathOrNil, commentOrNil)` / `setGameSettings(listOrNil)`	`nil`	Fallback setters
`setUserData(pathOrNil)` / `setResources(pathOrNil)` / `setDataLocal(pathOrNil)` / `setEncoding(valueOrNil)`	`nil`	Singleton setters, `nil` clears
`saveUser()` / `saveSubconfig(path)`	`nil`	Write to user config or loaded subconfig

Host Integration (Embedded Lua)

This crate's Lua support is host-embedded: your Rust application creates a Lua state and injects the openmwConfig table for scripts to consume. For setup and registration, use Lua Quick Start.

Typical mutation and persistence flow from Lua:

local cfg = openmwConfig.new(nil)
cfg:addContentFile("MyPlugin.esp")
cfg:setDataDirectories({"/path/to/data"})
cfg:setGameSetting("fJumpHeight,1.0", nil, nil)
cfg:saveUser()

Notes

Lua API naming is camelCase only.
Most method failures throw Lua runtime errors (pcall-friendly).
tryDefaultConfigPath(), tryDefaultUserDataPath(), tryDefaultLocalPath(), and tryDefaultGlobalPath() return (value, err) tuples instead of throwing.
This is not a standalone Lua module distribution (require("openmw_config")); integration is via Rust host registration.

Lua Stability Contract

Across 1.x releases, the documented openmwConfig.* constructors/default-path helpers and cfg:* read, mutate, and save method families are intended to remain stable.
Table shapes are stable:
- configChain() rows: { path, depth, status }
- gameSettings() / getGameSetting() rows: { key, value, kind }
status is one of loaded or skippedMissing.
kind is one of Color, String, Float, or Int.
nil inputs are used to clear optional settings in setter methods.

Quality & Testing

Unit and integration tests cover parser behavior across config chains, including replace=config queue semantics and missing subconfig traversal outcomes.
Roundtrip behavior is validated to preserve comments and fallback lexical forms where relevant.
Parse diagnostics include line context on malformed input variants for easier debugging.
CI/local lint posture is strict: cargo clippy --all-targets --features lua -- -W clippy::pedantic -D warnings.
Lua integration tests validate module exports, mutation flows, persistence, and error behavior.

Manual Diagnostics

The repository includes an ignored integration test that dumps the resolved real-world config chain to a local file for inspection.

Test: dump_real_config_chain_to_repo_local_file
Source: tests/integration_manual_chain_dump.rs
Output file: real_config_chain_paths.txt (repo root)
Purpose: verify chain resolution against your actual platform/user setup

Run it manually:

cargo test --test integration_manual_chain_dump -- --ignored --exact dump_real_config_chain_to_repo_local_file

Notes:

Run this when validating chain resolution on an actual machine/profile setup.
This test is intentionally ignored in normal test runs and CI.
Output format is one absolute openmw.cfg path per line, in traversal order.
It writes a local artifact intended for debugging and verification.

Compatibility Guarantees

Public APIs follow semver: breaking changes land only in a new major version.
MSRV is declared in Cargo.toml and may change only in a semver-compatible release with notes.
openmw.cfg behavior aims to match OpenMW docs for chain traversal and replace semantics.
Unknown keys are preserved during parse/serialize roundtrips.

Known Limitations

settings.cfg handling is intentionally deferred to a post-1.0 release.
This crate models openmw.cfg behavior only; it does not implement the entire OpenMW config stack.

Reference

OpenMW configuration documentation

See CHANGELOG.md for release history.

openmw-config is not affiliated with the OpenMW project.

Support

Has openmw-config been useful to you?

If so, please consider amplifying the signal through my ko-fi.

Thank you for using openmw-config.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

openmw-config 1.0.0