Chapter 2.6: Entity Manipulation

While the Entity I/O system (`EntFire`) is the standard, safest way to interact with entities, VScript provides a more direct and powerful—but also more dangerous—method for changing an entity's properties.

Directly Setting KeyValues: `__KeyValueFrom*`

Every entity in Hammer has a list of "KeyValues" (e.g., `targetname`, `_light`, `spawnflags`). VScript provides a family of functions, like `__KeyValueFromString()`, `__KeyValueFromInt()`, and `__KeyValueFromVector()`, to modify these values directly in memory.

// Find a dynamic light entity
local myLight = Entities.FindByName(null, "dynamic_light_prop");

if (myLight) {
    // --- The Standard Way (using I/O) ---
    // This sends a message to the entity, which then processes the color change.
    EntFireByHandle(myLight, "Color", "0 255 0", 0, null, null);

    // --- The Direct Way (using __KeyValueFrom) ---
    // This reaches directly into the entity's memory and changes the value.
    myLight.__KeyValueFromString("_light", "0 255 0");
}

At first glance, the direct method seems like a simple shortcut. However, it comes with a critical caveat.

The Danger of Bypassing Logic

⚠️ CRITICAL: `__KeyValueFrom*` does NOT trigger updates!

When you use `EntFire`, you are sending a message to the entity. The entity receives this message and runs its internal code to handle the change—updating its visuals, notifying the physics engine, synchronizing with the network, etc.

The `__KeyValueFrom*` functions bypass all of this logic. They change the data, but the entity doesn't "know" it has been changed. This can lead to desynchronization, where the visual state does not match the internal data. Effects may be delayed, partial, or simply not appear at all until another input forces the entity to refresh itself.

When to Use It (Carefully)

Despite the danger, this method has a key use case: setting up entities before they are spawned, typically via a `point_template`. By intercepting the pre-spawn logic, you can use `__KeyValueFrom*` to configure an entity with precise values before it ever exists in the world, ensuring it spawns in the exact state you want. For entities that are already active in the world, it is almost always better and safer to use `EntFire` or the high-level functions provided by libraries like PCapture-Lib.