source-vmf 0.6.0

A parser for Valve Map Format (VMF) files
Documentation

source-vmf

A straightforward, high-performance library for parsing, manipulating, and serializing Valve Map Format (VMF) files used in Source Engine games.

It provides a strongly-typed representation of map geometry, entities, visgroups, cameras, and cordons, while preserving unknown keys and custom blocks for lossless round-tripping.

Key Features

  • Lossless Round-tripping: Preserves unknown properties and custom vendor blocks across parse and serialize cycles.
  • Complete Map Coverage: Strongly-typed structures for version info, visgroups, view settings, world geometry (solids, sides), point and brush entities, cameras, and cordons.
  • Fast Entity Lookups: Search entities across visible and hidden blocks by targetname or name prefix using EntityIndex.
  • Entity I/O Connections: Ergonomic API for reading, modifying, and creating entity logic connections.
  • Atomic Saving: Writes safely to a temporary .part file before replacing the target file on disk.
  • Map Merging: Built-in helper to merge geometry, entities, visgroups, and cordons from multiple VMF files.
  • Serde Support: Optional serialization feature for serializing and deserializing VMF structures.

Feature Flags

  • serialization - Enables Serde Serialize and Deserialize implementations for VMF data structures.

Quick Start

1. Reading, Modifying, and Saving a Map

use source_vmf::prelude::*;

fn main() -> Result<(), VmfError> {
    let mut vmf = VmfFile::open("maps/de_dust2.vmf")?;

    println!("Map version: {}", vmf.versioninfo.map_version);

    // Find entities by classname
    for player_start in vmf.entities.find_by_classname("info_player_start") {
        println!("Spawn origin: {:?}", player_start.get("origin"));
    }

    // Create and add a new entity
    let mut tree = Entity::new("prop_static", 1000);
    tree.set("model".to_string(), "models/props_foliage/tree01.mdl".to_string());
    tree.set("origin".to_string(), "0 0 0".to_string());
    vmf.entities.push(tree);

    // Save atomically to disk
    vmf.save("maps/de_dust2_modified.vmf")?;

    Ok(())
}

2. Fast Lookups with EntityIndex

use source_vmf::prelude::*;

fn main() -> Result<(), VmfError> {
    let vmf = VmfFile::open("maps/test.vmf")?;
    let index = EntityIndex::build(&vmf);

    // Exact match by targetname (includes hidden entities)
    for &id in index.by_name("door_1") {
        if let Some(ent) = vmf.entity(id) {
            println!("Found door: {:?}", ent.classname());
        }
    }

    // Prefix search (e.g., all entities starting with "door_")
    for id in index.by_prefix("door_") {
        if let Some(ent) = vmf.entity(id) {
            println!("Matched entity: {:?}", ent.targetname());
        }
    }

    Ok(())
}

3. Adding Logic Connections

use source_vmf::prelude::*;

let mut button = Entity::new("func_button", 42);
button.add_connection(
    "OnPressed",
    "door_main",
    "Open",
    "",
    0.0,
    -1,
);

4. Merging Maps

use source_vmf::prelude::*;

fn main() -> Result<(), VmfError> {
    let mut base_map = VmfFile::open("maps/base.vmf")?;
    let prefab = VmfFile::open("maps/prefab.vmf")?;

    // Merges world solids, entities, hidden entities, visgroups, and cordons
    base_map.merge(prefab);
    base_map.save("maps/combined.vmf")?;

    Ok(())
}

License

MIT License.