Mapping/Custom Keyvalues - Revision history

Outerbeast at 18:43, 13 February 2025

2025-02-13T18:43:50Z

← Older revision		Revision as of 20:43, 13 February 2025
Line 25:		Line 25:
	<br>		<br>

	~~===~~== Custom keyvalues in Angelscript ~~===~~==		== Custom keyvalues in Angelscript ==
	Custom keyvalues can also be used from Sven Co-op's AngelScript API. Unlike other entity variables, custom keyvalues cannot be directly accessed by name. This is because they are created on demand, and can't be dynamically bound at runtime.		Custom keyvalues can also be used from Sven Co-op's AngelScript API. Unlike other entity variables, custom keyvalues cannot be directly accessed by name. This is because they are created on demand, and can't be dynamically bound at runtime.

Outerbeast: Added scripting information

2025-02-13T18:42:51Z

Added scripting information

@@ Line 24: / Line 24: @@
 * Key <code>$f_distance</code> on func_train: Float to add travelled distance to, causing power outage when you use it too much over specific amount of time.
 <br>
 Custom keyvalues can also be used from Sven Co-op's AngelScript API.
 [[Category:Mapping]]
 [[Category:Scripting]]

Outerbeast: Added categories

2025-02-13T18:40:15Z

Added categories

← Older revision		Revision as of 20:40, 13 February 2025
Line 25:		Line 25:
	<br>		<br>
	Custom keyvalues can also be used from Sven Co-op's AngelScript API.		Custom keyvalues can also be used from Sven Co-op's AngelScript API.

			[[Category:Mapping]]
			[[Category:Scripting]]

Outerbeast: Custom Keyvalues Guide

2023-03-13T21:40:18Z

Custom Keyvalues Guide

New page

== 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 <code>$</code>, 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:
* <code>$i_</code> makes the custom keyvalue an integer. (-2147483648 to 2147483647)
* <code>$f_</code> makes the custom keyvalue a float.
* <code>$v_</code> makes the custom keyvalue a 3D-vector, consisting of 3 floats.
* <code>$s_</code> makes the custom keyvalue a string.
 
Examples: <code>$i_donutseaten</code>, <code>$f_healthreserve</code>, <code>$v_vectortoenemy</code>, <code>$s_infotext</code>.
 
 
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.
== 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 <code>$i_energy</code> and value <code>50</code>. 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.
== 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 <code>$i_fuel</code> on a player: Store a number to represent jetpack fuel remaining.
* Key <code>$i_keycardlevel</code> on a player: Store a number to represent which level of security doors this player has access to.
* Key <code>$f_healthreg</code> on monsters: Float to determine how much health to restore per second on a global basis.
* Key <code>$f_distance</code> 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.