User:Blixibon/Mapbase wiki articles

From Valve Developer Community
Jump to: navigation, search

In the distant past, I considered putting Mapbase content on the VDC, and I occasionally did so. You can still see evidence of my efforts in the dedicated Mapbase article and the dedicated Mapbase entity category, with a few other mentions on shader articles or articles on more esoteric subjects, like Response System or Targetname. However, I was insecure about centralizing unofficial mod content on a Valve website and I didn't want to risk saturating existing articles with Mapbase content. The lack of moderation also eventually put me off from the VDC in general.

I stopped contributing to or regularly checking the VDC in 2022, but the mid-2024 moderator elections and subsequent increase in activity have reinvigorated my passion for modding and documentation, at least as of writing. However, to my surprise, other editors have picked up the work I started, spreading Mapbase around the VDC for better or for worse. There were apparently even debates over whether to consider it an engine branch or a mod... huh.

Even though I am the original developer of Mapbase, I don't actually have any intrinsic authority on how it's used or documented on the VDC. I am just one editor among many. However, these changes in the VDC's environment have made me reconsider my stance towards Mapbase's documentation on the VDC, and since Mapbase's independent wiki (which already used VDC-inspired formatting) has been in an effectively dilapidated state for several years, I'm using this page to experiment with adapting specific pages to the VDC.

Let me emphasize that this would NOT touch the wiki's landscape, and it probably wouldn't touch existing articles much at all. This isn't an omen for the next big cleanup project, or the next big mod promotion. This is just an experiment for having a few pre-existing Mapbase developer resources stand on the VDC as their own reference articles, and they would likely be centered within Category:Mapbase or even become subpages for the Mapbase article. They would be separate from articles relating to other games, and since they would serve as a central place to document certain Mapbase subjects, they may even deprecate certain instances of Mapbase being mentioned on other articles, or at least discourage them in the future.

If you have any comments or concerns about any of this, please leave them on this article's talk page.

Class Changes

These show all of Mapbase's new common I/O/KV.

Base Entity

Adapted from Base Entity

This page lists changes to CBaseEntity, which every single entity in the Source engine derives from. This means every entity in Hammer technically possesses these changes, but whether they actually show up depend on how relevant the changes are to a certain entity. (e.g. "Enable/DisableDraw" is irrelevant on logic entities)

Inputs

PassUser1 <string>
Causes this entity's OutUser1 output to be fired. Can pass any parameter.
PassUser2 <string>
Causes this entity's OutUser2 output to be fired. Can pass any parameter.
PassUser3 <string>
Causes this entity's OutUser3 output to be fired. Can pass any parameter.
PassUser4 <string>
Causes this entity's OutUser4 output to be fired. Can pass any parameter.
FireRandomUser
Fires OnUser1, OnUser2, OnUser3, or OnUser4 with a 25% chance of each.
PassRandomUser <string>
Fires OutUser1, OutUser2, OutUser3, or OutUser4 with a 25% chance of each. Can pass any parameter.

SetTarget <targetname>
A special new input designed to change an entity's "target", including things like path_track paths and env_gunfire targets. By default, this changes the common target keyvalue on entities. Some entities override SetTarget for their own keyvalues, e.g. scripted_sequence's target NPC. In code, this also calls Activate(), which is commonly used to assign m_target to cached entity handles.
SetOwnerEntity <targetname>
Sets this entity's "owner entity". Owner entities are mainly used for kill credit, and entities will typically never collide with their owner entity. Note that this has nothing to do with parenting.

SetHealth <integer>
Sets this entity's health. This input already existed on several entities, but now it's part of all entities.
AddHealth/RemoveHealth <integer>
Adds to/removes from this entity's health. These inputs already existed on props and func_breakables, but now they're part of all entities, including NPCs.
SetMaxHealth <integer>
Sets this entity's maximum health. This will not change the entity's current health unless it exceeds the new maximum, in which case the entity's health will be lowered down to the new maximum.

FireOutput <string>
Fires the named output on this entity. Format: <output name>:<activator>:<caller>:<parameter>:<delay> For example: OnDeath:my_entity:my_entity. Everything beyond the output name is optional.
RemoveOutput <string>
Removes all instances of the named output on this entity. Wildcards are supported, meaning you could just pass '*' to wipe all outputs from this entity.
AcceptInput <string>
Fires the named input on this entity. Format: <input name>:<parameter>:<activator>:<caller>:<output ID> Example: SetTarget:target_entity. Everything beyond the input name is optional. Note that this is arranged differently from FireOutput, having the parameter right after the input name.
CancelPending
Cancels any events fired by this entity that are currently pending in the I/O event queue. This input originated from logic_relay, but it's been promoted to a base input so any entity could cancel their outputs.

FreeChildren
Unparents all entities parented to this entity in a movement hierarchy.

SetLocalOrigin <vector>
Sets this entity's origin in local space, relative to its parent if one exists. Otherwise relative to the world.
SetLocalAngles <vector>
Set this entity's angles in local space, relative to its parent if one exists. Otherwise relative to the world.
SetAbsOrigin <vector>
Sets this entity's origin in the map, always relative to the world origin.
SetAbsAngles <vector>
Set this entity's angles, always relative to the world origin.
SetLocalVelocity <vector>
Sets this entity's current velocity.
SetLocalAngularVelocity <vector>
Sets this entity's current angular velocity.

AddSpawnFlags <integer>
Adds spawnflag(s) to this entity. Many spawnflags have their respective numbers suffixed in Mapbase's FGD.
RemoveSpawnFlags <integer>
Removes spawnflag(s) from this entity. Many spawnflags have their respective numbers suffixed in Mapbase's FGD.
SetRenderMode <integer>
Sets this entity's render mode.
SetRenderFX <integer>
Sets this entity's render FX.
SetViewHideFlags <integer>
Sets view ID hide flags. See Drawing entities in specific view IDs for more information.
Todo: Adapt here
AddEffects <integer>
Adds to this entity's effects flags.
RemoveEffects <integer>
Removes from this entity's effects flags.
EnableDraw <void> (also in Portal 2)
Draws this entity if it was undrawn before. Equivalent to RemoveEffects > 32.
DisableDraw <void> (also in Portal 2)
Undraws this entity if it was drawn before. Equivalent to AddEffects > 32.
AddEFlags <integer>
Adds EFlags to this entity.
RemoveEFlags <integer>
Removes EFlags from this entity.
SetMoveType <integer>
Sets this entity's movetype.
SetCollisionGroup <integer>
Sets this entity's collision group.
AddSolidFlags <integer>
Adds solid flags to this entity.
RemoveSolidFlags <integer>
Removes solid flags from this entity.

Touch <targetname>
Simulates the specified entity touching the entity receiving this input. (e.g. a trigger receiving this input with a player as the parameter will be triggered by that player)

KillIfNotVisible <void>
Kills this entity if it's not visible to any players.
KillWhenNotVisible <float>
Kills this entity when it's not visible to any players. The parameter is the delay before this is evaluated.

SetThinkNull <void>
Sets this entity's general think function to NULL. A string can be passed to clear the think of a specific context.

ChangeVariable <string>
A special version of AddOutput that changes a datadesc variable instead of a keyvalue, similar to logic_datadesc_accessor.

Outputs

OutUser1 <string>
Fires in response to PassUser1 input. Can pass any parameter.
OutUser2 <string>
Fires in response to PassUser2 input. Can pass any parameter.
OutUser3 <string>
Fires in response to PassUser3 input. Can pass any parameter.
OutUser4 <string>
Fires in response to PassUser4 input. Can pass any parameter.

OnKilled  (also in Left 4 Dead)
Fires when this entity is removed with the 'Kill' input.

KeyValues

View ID nodraw (viewhideflags) <flags>
Controls whether an entity shouldn't be drawn in specific parts of the view rendering process. See Drawing entities in specific view IDs for more information.
Todo: Adapt here
Disable flashlight (disableflashlight) <choices> (also in Portal 2)
Used to disable flashlight (env_projectedtexture) lighting on this entity.

The owner entity can now be accessed with the OwnerEntity keyvalue and m_fFlags can now be accessed with the aptly named m_fFlags keyvalue, but neither are actually used in any base FGD classes to avoid clutter.


Base NPC

Adapted from Base NPC

This page lists changes to CAI_BaseNPC, which every NPC derives from. This means every NPC in the game technically possesses these changes, although some changes might only be relevant to a specific group of them.

Some I/O were ported from other games or were already possible through other, more complicated means (e.g. keyvalues changed with AddOutput).

Inputs

SetHealthFraction <float>
Sets a NPC's health as a ratio in between 0 and 1. This input already existed on npc_helicopter, but it was expanded to be used on any NPC.

GiveWeaponHolstered <string>
Gives a NPC the specified weapon, but make it start holstered (meaning the NPC has to get it out on their own).
ChangeWeapon <string>
Holsters a NPC's current weapon, and then unholsters the specified weapon.
PickupWeapon <targetname>
Makes a NPC look for and pick up the specified weapon, which should be an entity in the world.
PickupItem <targetname>
Makes a NPC look for and pick up the specified weapon, which should be an entity in the world.

PickupItem <integer>
SetDynamicInteractions <integer>

AddCapabilities <flags>
Adds the specified Capability_t capabilities to a NPC.
RemoveCapabilities <flags>
Removes the specified Capability_t capabilities from a NPC.

SetCondition <string>
Adds the specified condition to a NPC. Can be the name or integer ID of the condition.
RemoveCondition <string>
Removes the specified condition from a NPC. Can be the name or integer ID of the condition.

SetHintGroup <string>
Sets a NPC's hint group.

SetThinkNPC <float>
Sets an entity's general think function to CallNPCThink. A float can be passed to delay this by a specific time.

SetDistLook <float>
Manually sets this NPC's sight distance. Pass '0' to reset.
SetDistTooFar <float>
Manually sets the distance in which NPCs will consider a target too far to attack. Pass '0' to reset.

SetSpeedModifier <float>
Set a float value to multiply movement animation speed.

Outputs

OnStateChange <integer>
Fires whenever a NPC changes state, passing the NPC's new state.

OnItemPickup <targetname>
Fires when a NPC picks up an item (e.g. a health vial), passing the item entity.

OnHolsterWeapon <targetname>
Fires when a NPC holsters their current weapon, passing the weapon entity.
OnUnholsterWeapon <targetname>
Fires when a NPC unholsters their current weapon, passing the weapon entity.

KeyValues

Friendly fire override (FriendlyFireOverride) <choices>
Dynamic interactions enabled (SetDynamicInteractions) <choices>
Spawn with StartScripting (SpawnWithStartScripting) <choices>
Spawns a NPC in the StartScripting state.
Speed Modifier (BaseSpeedModifier) <float>
Multiplies how far a NPC travels while moving. Does not affect the animation itself.

Base Combat Character

Adapted from Base Combat Character

This page lists changes to CBaseCombatCharacter, which both NPCs and players derive from. This means these changes can be used with either the player or NPCs, sometimes with varying behavior.

Inputs

SetProficiencyOverride <integer>
Overrides a character's weapon proficiency, or how accurate their shots are. -1 reverts to the character's default proficiency.
SetForceServerRagdoll <boolean>
Forces this character to turn into a serverside prop_ragdoll instead of a clientside ragdoll when it dies.

SetBloodColor <integer>
Sets a character's blood color.
SetRelationship <string>
Sets a character's relationship with another character, formatted as <target><disposition><priority>. This input originally only existed on NPCs, but it's been moved here so it can be used on players as well.

HolsterWeapon <void>
Holsters the character's current weapon. This input originally only existed on NPCs, but it's been moved here so it can be used on players as well.
HolsterAndDestroyWeapon <void>
Holsters the character's current weapon and destroys it. This input originally only existed on NPCs, but it's been moved here so it can be used on players as well.
UnholsterWeapon <string>
Unholsters the character's last weapon. This input originally only existed on NPCs, but it's been moved here so it can be used on players as well. A specific weapon can also now be specified in the parameter. If the specified weapon does not exist, it will be created.
SwitchToWeapon <string>
Makes the character switch to the specified weapon. On NPCs, this input "snaps" their active weapon to this one with no animation. If the specified weapon does not exist, it will be created.
GiveWeapon <string>
Gives the character the specified weapon. This input already existed on companions like citizens, but it's been moved so it can be used on all NPCs as well as players.
DropWeapon <string>
Makes the character the drop their current weapon, or a specific weapon.
PickupWeaponInstant <targetname>
Makes the character instantly pick up the specified weapon, which should be an entity in the world. This is similar to the "PickupWeapon" input on NPCs, but it's here so players can use it as well.

Additional NPC-specific weapon inputs exist. See Base NPC changes.

Outputs

OnWeaponEquip <targetname>
Fires when a character obtains a weapon in any way, including weapons it spawns with. Passes the weapon entity.
OnWeaponDrop <targetname>
Fires when a character drops a weapon. Passes the weapon entity.

OnKilledEnemy <targetname>
Fires when a character kills an enemy.
OnKilledPlayer <targetname>
Fires when a character kills a player.

OnHealthChanged <float>
Fires when a character's health changes, outputting a ratio in between 0 and 1 based on their current health and their max health.

KeyValues

Proficiency override (SetProficiencyOverride) <choices>
Overrides a character's weapon proficiency.
Force server ragdoll (SetForceServerRagdoll) <choices>
Forces this character to turn into a serverside prop_ragdoll instead of a clientside ragdoll when it dies.

Base Weapon

Adapted from Base Weapon

This page lists changes to CBaseCombatWeapon, which every weapon derives from. This means every weapon in the game technically possesses these changes, although some changes might only be relevant to a specific group of them.

Some I/O were already possible through other, more complicated means (e.g. keyvalues changed with AddOutput).

Inputs

SetAmmo1 <integer>
Sets the weapon's currently loaded primary ammo.
SetAmmo2 <integer>
Sets the weapon's currently loaded secondary ammo.
GiveDefaultAmmo <void>
Resets the weapon's loaded ammo to its default, which is usually the maximum amount.

EnablePlayerPickup <void>
Enables player pickup if it was disabled before.
DisablePlayerPickup <void>
Disables player pickup if it was enabled before.
EnableNPCPickup <void>
Enables NPC pickup if it was disabled before.
DisableNPCPickup <void>
Disables NPC pickup if it was enabled before.

BreakConstraint <void>
If the weapon was set to start constrained, this input breaks its constraint.

ForcePrimaryFire <void>
Forces the weapon to trigger its primary attack one time. This is supported on most guns, although implementation is weapon-specific and may function differently from weapon to weapon.
ForceSecondaryFire <void>
Forces the weapon to trigger its secondary attack one time. This is supported on most guns, although implementation is weapon-specific and may function differently from weapon to weapon.

Outputs

OnDropped <void>
Fires when dropped by a NPC or player, passing the dropper as the activator.

KeyValues

Ammo 1 (SetAmmo1) <integer>
Sets the weapon's currently loaded primary ammo. Requires the "Preserve ammo" spawnflag to function.
Ammo 2 (SetAmmo2) <integer>
Sets the weapon's currently loaded secondary ammo. Requires the "Preserve ammo" spawnflag to function.

Flags

  •  Deny NPC pickup : [8]
          Prevents NPCs from automatically picking up a weapon.
  •  Preserve ammo values when picked up : [16]
          Prevents the weapon from resetting its ammo values before being spawned, picked up, dropped, etc.

NPC/player interaction with weapons

Mapbase adds a bunch of weapon-related I/O/KV to NPCs and players, covered on the Base NPC and Base Player sections for NPC or player-specific changes and Base Combat Character for changes used by both types.

Entity Groups

Changes and augmentations to specific groups of entities.

Filters

Adapted from Filters

A filter tests a certain condition or set of conditions to filter through entities, like a trigger_once using a filter_activator_name that only allows an entity with the name "cow" to pass it. Click here for more information on filters in Source.

In Mapbase, all filters have been given the following new I/O/KV:

Inputs

TestEntity <targetname>
Tests the filter against the specified entity and fires OnPass or OnFail based on the result. This is similar to the existing TestActivator input, which only tests the activator of the triggering output.
SetField <string>
Sets this filter's primary testing criteria. In a filter_activator_name, this would be the name to test against the activator.

KeyValues

Pass caller when tested (PassCallerWhenTested) <choices>
When tested with TestActivator or TestEntity inputs, this causes the OnPass and OnFail outputs to use the entity that called the test as the caller instead of the filter itself.

New filters

Mapbase adds a few new filters so that mappers could test more conditions:

Name Description
filter_activator_model Filters an entity by its model's name. This entity already exists in all games starting with Left 4 Dead Left 4 Dead, but Mapbase adds the option to filter by skin and supports matchers.
filter_activator_context Filters an entity by its response contexts. This entity already exists in all games starting with Left 4 Dead Left 4 Dead, but Mapbase allows for multiple contexts to be used at once and supports matchers.
filter_activator_squad Filters an NPC by its squad name, with the option to deny silent members. (enemy finders, vital allies in player_squad, etc.)
filter_activator_hintgroup Filters an NPC by its hint group, with the option to filter Hint Limit Nav.
filter_activator_keyfield Filters an entity by its keyvalues, serving as an extension of logic_keyfield.
filter_activator_relationship Filters an entity by its relationship to a target, or vice versa.
filter_activator_classify Filters an entity by its Classify() class. (e.g. CLASS_PLAYER_ALLY)
filter_activator_criteria Filters an entity by response criteria normally used in the response system.
filter_activator_involume Filters an entity by whether it's inside of a target entity's volume. (e.g. a trigger)
filter_activator_surfacedata Filters an entity by its surface data. (e.g. whether it's made of wood)

Redirect filters

Redirect filters are a new family of filters that take a separate entity from the activator and pass it to another filter. For example, a trigger_once using a filter_redirect_weapon gets the activator's weapon and passes it to a filter_activator_class, which checks if it's a weapon_pistol.

Here's a list of the redirect filters introduced in Mapbase:

Name Description
filter_redirect_weapon Redirects the activator's weapon. When used as a damage filter, this gets the weapon used in the damage.
filter_redirect_owner Redirects the activator's owner entity.
filter_redirect_inflictor When used as a damage filter, this redirects the inflictor of the damage, e.g. the grenade in an explosion. (filters normally use the attacker)

Damage manipulators

Damage manipulators are a new family of filters designed to be used as damage filters, directly manipulating or operating with damage in some way. They don't actually filter anything themselves, but they can have a "secondary filter" to act as an actual damage filter or to further control their behavior.

4 of these entities exist in Mapbase:

Name Description
filter_damage_transfer Causes damage taken by entities using this filter to transfer to a different entity, or a set of entities.
filter_damage_mod Modifies damage taken by entities using this filter.
filter_damage_logic Fires outputs with damage parameters whenever an entity using this filter takes damage.
filter_blood_control Controls whether blood can be emitted when an entity using this filter takes damage. (does not affect actual damage on its own)

filter_script

filter_script is a special filter which allows filter functions to be controlled by VScript. See VScript for more information on VScript.

Todo: Dedicated VScript in Mapbase article listing filter_script's hooks?

Reference Articles

Drawing entities in specific view IDs

Adapted from Drawing entities in specific view IDs

Mapbase adds a new keyvalue that could prevent entities from being drawn in any of the drawing passes used in the view rendering process. For example, if an entity is set to not draw in VIEW_MONITOR, that entity won't show up on RT camera monitors. It will show up everywhere else (player's eyes, mirrors, etc.), but it just won't show up on cameras.

Any combination of view IDs could be used.

View ID list

  • VIEW_MAIN - 1
  • VIEW_3DSKY - 2
  • VIEW_MONITOR - 4
  • VIEW_REFLECTION - 8
  • VIEW_REFRACTION - 16
  • VIEW_INTRO_PLAYER - 32
  • VIEW_INTRO_CAMERA - 64
  • VIEW_SHADOW_DEPTH_TEXTURE - 128
  • VIEW_SSAO - 256

FGD presets

  • 0 : "Draw normally"
  • 193 : "Hide in main view (player's eyes)" // VIEW_MAIN + VIEW_INTRO_CAMERA + VIEW_SHADOW_DEPTH_TEXTURE
  • 36 : "Hide in cameras" // VIEW_MONITOR + VIEW_INTRO_PLAYER
  • 24 : "Hide in mirrors/water" // VIEW_REFLECTION + VIEW_REFRACTION
  • 60 : "Hide in cameras and mirrors/water" // VIEW_MONITOR + VIEW_INTRO_PLAYER + VIEW_REFLECTION + VIEW_REFRACTION
  • 2 : "Hide in 3D skybox" // VIEW_3DSKY
  • 128 : "Hide projected texture shadows" // VIEW_SHADOW_DEPTH_TEXTURE