Crate dream_path 

Byte-first normalized virtual resource paths.

dream-path owns the path normalization shared by archive readers, VFS, resource loading, rendering-side resource lookup, and tooling. The rules are intentionally the boring OpenMW-style virtual path rules:

• \ becomes /
• ASCII uppercase letters become lowercase
• repeated separators collapse
• leading separators are discarded
• arbitrary non-UTF-8 bytes are preserved

The rules are byte-literal: /// normalizes to an empty byte string, while a non-leading trailing separator is kept (foo/ stays foo/).

It does not decode legacy filename encodings, perform Unicode normalization, case-fold non-ASCII text, interpret host filesystem paths, or compute archive-format hashes. Those are separate jobs. Mixing them into the path type would be a small architectural crime, so naturally we avoid doing that.

Lua API

Enable the lua feature to embed the same byte-preserving normalization API into an existing mlua::Lua state. lua::create_module builds the API table without registering a global, while lua::register_module installs it as the default dream_path global.

The lua feature does not choose a Lua backend. Engine/application crates own that decision and should enable exactly one shared mlua runtime for the final dependency graph. DreamWeave recommends LuaJIT in 5.2 compatibility mode and does not currently test these bindings against other Lua runtimes. If a host chooses another backend, it owns that compatibility burden. For standalone documentation and local smoke tests, the standalone-lua feature enables lua plus mlua’s luajit52 and vendored features.

The Lua API treats Lua strings as raw path bytes, preserving invalid UTF-8 and embedded NUL bytes. It is embed-only: this crate does not provide a cdylib Lua module loader, and hosts that already own a different Lua runtime should bind the Rust byte API themselves.

Modules

lua

Embedded Lua bindings for byte-first path normalization.

Structs

NormalizedPath

A byte-first normalized virtual resource path.

Traits

ByteSlice

A trait that extends &[u8] with string oriented methods.

Functions

extension_normalized

Return the extension of the final component of an already-normalized virtual path, without the dot.

file_name_normalized

Return the final non-empty component of an already-normalized virtual path.

is_normalized_path

Return true if path already matches this crate’s normalized spelling.

normalize_path

Normalize a virtual resource path into owned bytes.

normalize_path_in_place

Normalize an owned virtual resource path in place.

normalize_path_into

Normalize a virtual resource path into an existing buffer.

normalize_path_owned

Normalize an owned virtual resource path, reusing its allocation.

parent_normalized

Return the parent portion of an already-normalized virtual path.