09-Jul-2023
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 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.
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.
| 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. |
| 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. |
| 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. |
| 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. |
| 3 | DEAD_RESPAWNABLE | <unknown> |
| 4 | DEAD_DISCARDBODY | <unknown> |
| 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. |
| 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. |
| 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. |
| 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) |
| 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. |
| 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!) |
| 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. |
| 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) |
