source-vmf 0.6.1

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

```rust,no_run
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

```rust,no_run
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

```rust
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

```rust,no_run
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.