dream-path

Byte-first normalized virtual resource paths for DreamWeave and OpenMW-style asset lookup.

Archive readers, VFS code, resource loading, render-side lookup and tooling all turn a path into a key. dream-path is the one place that happens, so they agree: five subtly different normalizers is how you get five subtly different bugs. It normalizes the byte spelling of virtual resource paths. It is not a file system abstraction.

Documentation, including the full Rust and Luau API reference: https://dreamweave-mp.github.io/dream_path/

cargo add dream-path

One dependency, bstr, re-exported as dream_path::bstr.

• \ becomes /
• ASCII A to Z become lowercase
• repeated separators collapse, and leading separators are removed
• every other byte is kept: invalid UTF-8, non-ASCII, NUL, .., a trailing /

No legacy decoding, no Unicode folding, no host path or URI interpretation, no archive hashes. Those are other crates' jobs.

use std::collections::HashMap;

use dream_path::{NormalizedPath, normalize_path_into};

let mut meshes = HashMap::new();
meshes.insert(NormalizedPath::new(r"//Meshes\x\Ex_Door.NIF"), 7);

// Look up by borrowed bytes: normalize the query into a buffer you reuse.
let mut scratch = Vec::new();
normalize_path_into(&mut scratch, br"Meshes\X\EX_DOOR.nif");
assert_eq!(meshes.get(scratch.as_slice()), Some(&7));

With the lua feature, dream_path::lua::PathExtension is an l3i extension providing the module @dream/path. The host composes it into its RuntimePlan; the crate never creates a VM or installs a global.

local dreamPath = require("@dream/path")
assert(dreamPath.normalize([[Textures\Foo.DDS]]) == "textures/foo.dds")
assert(dreamPath.extension([[Textures\Foo.DDS]]) == "dds")

• Normalization: every rule and its literal consequences
• Keys and lookups: which function to use where
• Embedding Luau: l3i setup, and moving from the 0.2 mlua binding
• Rust API and Luau API
• Changelog

Rust 1.88. dream-path is licensed under either of MIT or Apache-2.0, at your option. Releases up to and including 1.0.0 were GPL-3.0-only.

Has dream-path been useful to you? Consider amplifying the signal through ko-fi.