Mapping/Custom Keyvalues

1 Introduction

Custom keyvalues are a new feature in Sven Co-op 4.6. Using custom keyvalues, you can store any and as much information as you want on any entity with any names you desire. While normal keyvalues will be read into internal data structures of the entity and unknown keyvalues will be discarded, custom keyvalues will simply be stored on the respective entity. The entity won't care about what you set. Custom keyvalues are identified by a leading dollar sign $, followed by a type-specifier. When accessing a custom keyvalue which is unset, the game will read the type-specifier to initialize the variable as either an integer (a whole number), a float (a decimal digit), a vector (a triple of 3 floats) or a string (a text/text-fragment/array of chars) and initialize it with a default value of zero for anything numeric and an empty string for the string type.
The following 4 type specifiers exist, whereas the underscore is part of them:

• $i_ makes the custom keyvalue an integer. (-2147483648 to 2147483647)
• $f_ makes the custom keyvalue a float.
• $v_ makes the custom keyvalue a 3D-vector, consisting of 3 floats.
• $s_ makes the custom keyvalue a string.

Examples: $i_donutseaten, $f_healthreserve, $v_vectortoenemy, $s_infotext.

A note on the float datatype: This data type can represent huge numbers with over 30 digits before the decimal point, in negative as well as positive number-space. However, the further away the number is from 0.0, the less precise it is represented. For example 10.4 will be so close to 10.4 in the float data type that you can assume they're practically the same, but 10000.4 will actually become about 10000.400391. This is relatively obsolete, depending on how great precision you require.

What a vector is: Simply a grouped set of 3 floats, which is either used to represent pitch, yaw and roll and thus define an angle in 3D-space, or an x-, y- and z-extent to define a direction and distance in 3D-space. E.g. when you take a running jump from the top ofa skyscraper, you end up with great negative z-/height-velocity and some y-/forward-velocity, but not really any x-/right-velocity, e.g. "0.0 300.0 -1800.0", without the quotes, where the single values represent speed in units per second into their according dimensions.

2 Setting Custom Keyvalues

There are different ways to set a custom keyvalue. The most straightforward way is to view an entity's properties in Valve Hammer Editor, disable the Smart-Edit-mode and add the key manually, e.g. key $i_energy and value 50. You can also set custom keyvalues through trigger_changevalue and trigger_copyvalue, or use them as a source to write to another keyvalue (in trigger_copyvalue). You can compare them among each other and normal keyvalues through trigger_condition. You can also set them when creating an entity with trigger_createentity. Custom keyvalues are pretty flexible to store whatever you need and to operate on that however you require.

3 Motivation

The main reason custom keyvalues were implemented was to give mappers an alternative to the few unused base keyvalues to store data on entities. Here are several possible usage scenarios to inspire you:

• Key $i_fuel on a player: Store a number to represent jetpack fuel remaining.
• Key $i_keycardlevel on a player: Store a number to represent which level of security doors this player has access to.
• Key $f_healthreg on monsters: Float to determine how much health to restore per second on a global basis.
• Key $f_distance on func_train: Float to add travelled distance to, causing power outage when you use it too much over specific amount of time.

Custom keyvalues can also be used from Sven Co-op's AngelScript API.