Entity Keyvalues




Within Valve Hammer Editor's .rmf- and .map-file formats, all keyvalues are saved as pairs of two strings - the key's name and the value - even if a value is a number. A string is a row/chain of chars, or simply, a piece of text if that is easier for you to grasp, which's end is defined by a byte with all bits set to zero, called the null-terminator. However, this is not continuously the case in game. When the map loads, known keyvalues are parsed into the entities' internal data structures of different types. If a keyvalue is not know, it will be discarded and then can no longer be read after the map has loaded.

Entity-specific keyvalues

Entity-specific keyvalues are keyvalues which exist for specific entity classes only. They are the direct property of the respective entity and meddling with them from the outside can easily cause undefined behaviour. The entity might rely on an entity-specific keyvalue to manage its internal state, or it only parses it once when it spawns and does not care about it after that. It might also be perfectly safe to change it and work without problems. In short: It depends. If you want to change an entity-specific keyvalue, ask in the SC Forums whether your ambition is safe or not. Some entity-specific keyvalues can be read and written through trigger_changevalue, trigger_copyvalue and trigger_condition; for example, all keyvalues of trigger_entity_iterator are supported. The majority of entity-specific keyvalues is not supported, yet, and can only be replaced directly. I'll spare you from the technical details and let you know the range of supported entity-specific keyvalues is worked on being expanded. Entity-specific keyvalues can often (but not always) be identified through what they read, e.g. "m_isz" (usually a string then), "m_i" (integer), "m_f*" (float), and so forth. However, the underscore may be missing, or the keyvalue may not have any hints like that at all! There is one absolute method to figure out if a keyvalue from the FGD is an entity-specific keyvalue: If it is not a base keyvalue.

Base Keyvalues/Private Entity Variables

By base keyvalues, I am refering to private entity variables ("PEV") which are inherited by all entities from the entity base class. This means, that no matter what entity you are dealing with, it has the ability to store these basic keyvalues. There is a total of exactly 123 (what a nice number) private entity variables. These values are often kept up to date between server and client and are supposed to cover all sorts of generic information, like position in the map, velocity, visual appearance, health and armor. As a result, not all entities do require all their base keyvalues; not at all. A lot of them are unused for specific entities. Henceforth, despite making no sense until now, a lot of base keyvalues are abused to store information which is unrelated to what they're called, because of programming convenience. This is good for us, because base keyvalues can be read and written from the outside, while entity-specific keyvalues can only be overwritten, and we can easily tell which base keyvalues correspond to what data by switching Smart-Edit-mode in VHE off or by just checking the FGD. Many of these can be touched without second thought, while some will exact vengeance on you if you do.

Here is a list of all base keyvalues. All entities do have these, even if they do not show up in Valve Hammer Editor. Most of them have an expected functionality/original purpose. However, the exact ways they are used by the respective entities are all up to the game engine.

Key name Val. type Description Example value
classname String Classname of that entity. "func_train"
globalname String Global name used for level transitions. "map02_scientist_003"
origin 3D-Vector Position of the entity in world coordinates. 30 60 90
oldorigin 3D-Vector Old position. Always 0 0 0 in engine. 0 0 0
velocity 3D-Vector Direction and speed of the entity. 100 20 0
basevelocity 3D-Vector Base direction and speed of the entity. (for example if standing on a train) 100 20 0
clbasevelocity 3D-Vector Used by client. 100 20 0
movedir 3D-Vector Movement direction used by trigger_push or func_rotating. 0.5 1 0
angles 3D-Vector Angles of the entity. (pitch, yaw, roll) 0 90 0
avelocity 3D-Vector Angular velocity. (rotational speed, degrees per second) 0 25 0
punchangle 3D-Vector Auto-decaying view angle adjustment. (e.g. when an alien grunt punches you) 0 25 0
v_angle 3D-Vector Viewing angle. (player only) 0 25 0
endpos 3D-Vector End position; used by some moving entities. 500 100 0
startpos 3D-Vector Start position, used by some moving entities 100 0 0
impacttime Float - -
starttime Float - -
fixangle Integer Value to tell the engine, what to do with the entity angles. 0: nothing; 1: force view angles; 2: add avelocity. 0
idealpitch Float - -
pitch_speed Float - -
ideal_yaw Float - -
yaw_speed Float - -
modelindex Integer Index of the entity model. 23
model String Name of the entity model. "models/scientist.mdl"
viewmodel Integer Player's viewmodel. (what you see in first person) 23
weaponmodel Integer Player's weaponmodel. (what other players see when they look at you) 23
absmin 3D-Vector Absolute mins; coordinates of the lower left back corner of the entity hull in world space. 100 100 0
absmax 3D-Vector Absolute maxs; coordinates of the upper right front corner of the entity hull in world space. 132 132 32
mins 3D-Vector Entity hull mins; coordinates of the lower left back corner of the entity hull. -16 -16 -16
maxs 3D-Vector Entity hull maxs; coordinates of the upper right front corner of the entity hull. 16 16 16
size 3D-Vector Entity hull size. 32 32 32
ltime Float - -
nextthink Float Time-value of the entity, telling the engine when to call the "think"-function of the entity next, which may compute and execute several entity functionalities. (e.g. train movement) (depends on server time value)
movetype Integer Movetype-value, telling engine how this entity should behave physically. (see movetype value list below) 1
solid Integer Solid-value, telling engine how OTHER entities should behave physically when they touch this entity. (see solid value list below) 1
skin Integer Skin of this entity. (texture selection for studiomodels) 1
body Integer Body of this entity. (sub-model selection for studiomodels) 1
effects Integer Effects-flag, telling the engine how to render this entity. (see effects value list below) 1
gravity Float Percentage of "normal" gravity. 100
friction Float Used by engine when movetype is MOVETYPE_BOUNCE (inverse elasticity); used by several entities for friction. (e.g. func_pushable) 100
light_level Integer - -
sequence Integer Current animation sequence. 3
gaitsequence Integer Movement animation sequence for player. (0 for none) 2
frame Float Percentage of playback position in animation sequences. (0 - 255) 102
animtime Float World time when frame was set. (depends on server time value)
framerate Float Animation playback rate. (-8x to 8x) 3
controller byte[4] Bone controller setting. (0 - 255) 110 20 0 80
blending byte[2] Blending-amount between sub-sequences. (0 - 255) 200 120
scale Float Sprite rendering scale. (0 - 255) 0.25
rendermode Integer Render-mode. (see list of rendermode modes below)
renderamt Float Render-amount. 255
rendercolor 3D-Vector Render-color for color render-mode. 255 128 32
renderfx Integer Render-effect. (see list of renderfx modes below)
health Float Health-points of the entity. Use it in trigger_camera to check if this camera is used (1 for camera is being used, 0 for not). 100
frags Float Frags of the entity. 100
weapons Integer Bit-mask for available weapons. -
takedamage Integer Takedamage-value, telling the engine if and how this entity can take damage. (see list of takedamage values below) 0
deadflag Integer Deadflag-value, telling the engine what the life/death status of the entity is. (see list of deadflag values below) 0
view_ofs 3D-Vector View offset vector. 8 0 32
button Integer Button-flags, sent from client telling the server, which buttons are pressed. (see list of button values below) 0
impulse Integer - -
chain Entity Entity-pointer when linked into a linked list. Entity-pointer or NULL.
dmg_inflictor Entity Entity-pointer to the entity that did damage to this entity. Entity-pointer or NULL.
enemy Entity Entity-pointer to the current enemy this entity is focusing on. Entity-pointer or NULL.
aiment Entity Entity-pointer when movetype is MOVETYPE_FOLLOW. Entity-pointer or NULL.
owner Entity Entity-pointer when this entity is owned by another entity. Examples: When a func_tank is being used by a player, the tank's owner is that player. An RPG fired by a player is owned by that player. Entities have no collision with their owner and vice versa. Entity-pointer or NULL.
groundentity Entity Entity-pointer to the entity where this entity is standing on. (includes "worldspawn" for map) Entity-pointer or NULL.
spawnflags Integer Spawnflags, set by mapper. 0
flags Integer Flags, set by engine. (see list of flags below) 0
colormap Integer Low byte topcolor; high byte bottomcolor. This specifies model custom colors, as seen in use on player models. 57020
topcolor Integer Top color of player model. 225
bottomcolor Integer Bottom color of player model. 225
team Integer - -
classify Integer Classification of this entity used in monsters relationship. Can be used with monsters, breakables (including doors) and any other targetable entity (in mean of attack). (see list of classify values below)
max_health Float Maximum health this entity can have. 100
teleport_time Float - -
armortype Float Maximum armor this entity can have. 100
armorvalue Float Armor points of this entity. 100
waterlevel Integer Value to tell the server if the entity is swimming, on dry ground or wading. (see list of waterlevel values below)
watertype Integer Watertype. (slime, lava, water) 0
target String Name of the target of this entity. "top_sprite"
targetname String Name of this entity. "trigger_top_sprite_on"
netname String Used in several ways, see FGD or ask someone. For players, this contains their nickname. "lalala"
message String Used in several ways, see FGD or ask someone. "lalala"
dmg_take Float - -
dmg_save Float - -
dmg Float Amount of damage this entity will inflict on others if it deals damage. 10
dmgtime Float - -
noise String - -
noise1 String - -
noise2 String - -
noise3 String - -
speed Float Speed of this entity (not current speed; that's what velocity is!) 100
air_finished Float - -
pain_finished Float - -
radsuit_finished Float - -
pContainingEntity Entity Entity-pointer. (?) Entity-pointer or NULL
playerclass Integer - -
maxspeed Float Maximum speed of this entity. 200
fov Float Field of view 90
weaponanim Integer - -
pushmsec Integer - -
bInDuck Integer 1 if crouching, 0 otherwise. 0
flTimeStepSound Integer Time-delay for step sounds. (?) -
flSwimTime Integer - -
flDuckTime Integer - -
iStepLeft Integer - -
flFallVelocity Float - -
gamestate Integer - -
oldbuttons Integer - -
groupinfo Integer - -
iuser1 - iuser4 Integer User-defined integer-values, used by Sven Co-op on several entities in different ways. -
fuser1 - fuser4 Float User-defined float-values, used by Sven Co-op on several entities in different ways. -
vuser1 - vuser4 3D-Vector User-defined vectors, used by Sven Co-op on several entities in different ways. -
euser1 - euser4 Entity User-defined entity-pointers, used by Sven Co-op on several entities in different ways. -

What follows is several tables explaining what different values mean for various base keyvalues. Since SC 4.6, you can also write the value name instead of the numeric value, given that it fits the targeted keyvalue type. You then can also put a leading tilde ('~') to perform bitwise negation, which is useful for flags.

List of "flags"-flags

Flag Value Flag Name Description
1 FL_FLY Entity can fly.
2 FL_SWIM Entity can swim.
4 FL_CONVEYOR Entity is a conveyor.
8 FL_CLIENT Entity is a client/player.
16 FL_INWATER Entity is in water.
32 FL_MONSTER Entity is a monster.
64 FL_GODMODE Entity is invincible.
128 FL_NOTARGET Entity won't be attacked by enemies.
256 FL_SKIPLOCALHOST Don't tell clients abouts this entity; they're predicting this entity by themselves.
512 FL_ONGROUND Entity is on the ground.
1024 FL_PARTIALGROUND At least one of the 4 corners of this entity's hull does not touch the ground.
2048 FL_WATERJUMP Player jumping out of water.
4096 FL_FROZEN Player is frozen. (Whilst a trigger_camera-sequence)
8192 FL_FAKECLIENT Fake client, simulated server side; don't send network messages to them. (Used for bots)
16384 FL_DUCKING Player is fully crouching.
32768 FL_FLOAT Entity can float on water.
65536 FL_NOWEAPONS Denies use of player weapon.

List of "button"-flags

Flag Value Flag Name Description
1 IN_ATTACK Primary-button attack pressed.
2 IN_JUMP Jump-button pressed.
4 IN_DUCK Duck-button pressed.
8 IN_FORWARD Forward-button pressed.
16 IN_BACK Backward-button pressed.
32 IN_USE Use-button pressed.
64 IN_CANCEL <unknown>
128 IN_LEFT Turn left-button pressed.
256 IN_RIGHT Turn right-button pressed
512 IN_MOVELEFT Strafe left-button pressed.
1024 IN_MOVERIGHT Strafe right-button pressed.
2048 IN_ATTACK2 Secondary attack-button pressed.
4096 IN_RUN Walk-button pressed.
8192 IN_RELOAD Reload-button pressed.
16384 IN_ALT1 Left "Alt"-button pressed.
32768 IN_SCORE Scoreboard-button pressed.

List of "CommonEntityFlags"-flags

Flag Value Flag Name Description
1024 SF_NORESPAWN Set this bit on guns and stuff that should never respawn. .
2048 SF_DELAYREMOVE A weapon will be removed from the map after 60sec.
4096 SF_CREATEDWEAPON This flag indicates that this entity is a weapon created for players, as opposed to being created by being placed by a mapper.
8192 SF_DODAMAGE This flag indicates that a player thrown weapon should deal damage to things it hits.
16384 SF_GIVENITEM This item is being given to the player - can't fall out of map.
32768 SF_NODEFAULTAMMO Don't allow default ammo to be set. Prevents players from getting too much ammo from cross map inventory.

List of "deadflags"-states

State Value State Name Description
0 DEAD_NO Alive.
1 DEAD_DYING Playing death animation or corpse still falling off of a ledge waiting to hit the ground.
2 DEAD_DEAD Dead; lying still.

List of "takedamage"-states

State Value State Name Description
0 DAMAGE_NO Does not take damage.
1 DAMAGE_YES Does take damage.
2 DAMAGE_AIM Does only take damage from aiming weapons.

List of "solid"-states

State Value State Name Description
0 SOLID_NOT No interaction with other objects.
1 SOLID_TRIGGER Notice touch, but don't block.
2 SOLID_BBOX Touch on edge, block.
3 SOLID_SLIDEBOX Touch on edge, but not if other is on ground.
4 SOLID_BSP BSP clip, touch on edge, block.

List of "waterlevel"-states

State Value State Name Description
0 WATERLEVEL_DRY Not in water.
1 WATERLEVEL_FEET Feet underwater.
2 WATERLEVEL_WAIST Waist underwater.
3 WATERLEVEL_HEAD Head underwater.

List of "movetype"-states

State Value State Name Description
0 MOVETYPE_NONE Never moves.
3 MOVETYPE_WALK Player only; moving on the ground.
4 MOVETYPE_STEP Gravity, special edge handling; monsters use this.
5 MOVETYPE_FLY No gravity, but still collides with stuff.
6 MOVETYPE_TOSS Receive gravity and collisions.
7 MOVETYPE_PUSH No clip to world; push and crush. (e.g. func_train)
8 MOVETYPE_NOCLIP No gravity; no collisions; still handle velocity and angular velocity.
9 MOVETYPE_FLYMISSILE Handled as if was larger for monsters. (Collides more easily)
10 MOVETYPE_BOUNCE Just like "Toss", but reflect velocity when contacting surfaces. (E.g. when dropping weapons/ammo)
11 MOVETYPE_ BOUNCEMISSILE Like "Bounce", but without gravity.
12 MOVETYPE_FOLLOW Track movement of aiming entity.
13 MOVETYPE_PUSHSTEP BSP model that needs gravity and world collisions; uses nearest hull for world collision. (e.g. func_pushable)

List of "effects"-states

Flag Value Flag Name Description
1 EF_BRIGHTFIELD Swirling cloud of yellow particles. (Used when a monster is stuck in wall to receice the level designer's attention)
2 EF_MUZZLEFLASH Single frame ELIGHT on entity attachment 0.
4 EF_BRIGHTLIGHT DLIGHT centered at entity origin.
8 EF_DIMLIGHT Player flashlight.
16 EF_INVLIGHT Get model-lighting from ceiling. (Barnacles have this)
32 EF_NOINTERP Don't interpolate the next frame.
64 EF_LIGHT Rocket flare pulsing glow sprite.
128 EF_NODRAW Don't draw entity. (Brush- basedtriggers have this)
256 EF_NOANIMTEXTURES Never animate a texture on given brush.
512 EF_FRAMEANIMTEXTURES Never animate a texture on given brush. but if the brush has a "frame" value, the corresponding animating texture is used.
1024 EF_SPRITE_CUSTOM_VP Override sprite viewport draw mode with the type specified in key "sequence".
2048 EF_NODECALS No decals will be drawn on this entity.

List of "renderfx"-states

Value State Name Description
0 kRenderFxNone Normal render mode.
1 kRenderFxPulseSlow Slow pulse.
2 kRenderFxPulseFast Fast pulse.
3 kRenderFxPulseSlowWide Slow wide pulse.
4 kRenderFxPulseFastWide Fast wide pulse.
5 kRenderFxFadeSlow Slow fade away.
6 kRenderFxFadeFast Fast fade away.
7 kRenderFxSolidSlow Slow become solid.
8 kRenderFxSolidFast Fast become solid.
9 kRenderFxStrobeSlow Slow strobe.
10 kRenderFxStrobeFast Fast strobe.
11 kRenderFxStrobeFaster Faster strobe.
12 kRenderFxFlickerSlow Slow flicker.
13 kRenderFxFlickerFast Fast flicker.
14 kRenderFxNoDissipation Constant glow.
15 kRenderFxDistort Distort/scale/translate flicker.
16 kRenderFxHologram kRenderFxDistort + distance fade
17 kRenderFxDeadPlayer kRenderAmt is the player index
18 kRenderFxExplode Scale up really big!
19 kRenderFxGlowShell Glowing Shell
20 kRenderFxClampMinScale Keep this sprite from getting very small. (sprites only!)

List of "rendermode"-states

State Value State Name Description
0 kRenderNormal Normal render mode.
1 kRenderTransColor Color with transparency render mode.
2 kRenderTransTexture Texture with transparency render mode.
3 kRenderGlow Glow render mode.
4 kRenderTransAlpha Texture with transparency and alpha render mode.
5 kRenderTransAdd Additive render mode.

List of "classify"-states

Value State Name Description
-1 CLASS_FORCE_NONE Forces class override to none.
0 CLASS_NONE No classification.
1 CLASS_MACHINE Is machine.
2 CLASS_PLAYER Is player.
3 CLASS_HUMAN_PASSIVE Is passive human.
4 CLASS_HUMAN_MILITARY Is military human.
5 CLASS_ALIEN_MILITARY Is military alien.
6 CLASS_ALIEN_PASSIVE Is passive alien.
7 CLASS_ALIEN_MONSTER Is monster alien.
8 CLASS_ALIEN_PREY Is prey alien.
9 CLASS_ALIEN_PREDATOR Is predator alien.
10 CLASS_INSECT Is insect.
11 CLASS_PLAYER_ALLY Is player ally.
12 CLASS_PLAYER_BIOWEAPON Is player bioweapon.
13 CLASS_ALIEN_BIOWEAPON Is alien bioweapon.
14 CLASS_XRACE_PITDRONE Is X-Race pitdrone
15 CLASS_XRACE_SHOCK Is X-Race shock trooper (also Voltigores)
16 CLASS_TEAM1 Is on Team 1 (used to put players into teams to enable special features)
17 CLASS_TEAM2 Is on Team 2 (used to put players into teams to enable special features)
18 CLASS_TEAM3 Is on Team 3 (used to put players into teams to enable special features)
19 CLASS_TEAM4 Is on Team 4 (used to put players into teams to enable special features)
99 CLASS_BARNACLE Is Barnacle (used by xen trees/spores, Barnacle is Alien Predator)