Mapping/Game Triggering System

1 Introduction

The game engine holds all entities in one chained list. Every entity has an internal unique entity id by which it can be referenced. For every entity there is, one edict is required. An edict is a sort of entity slot. The default amount of edicts is 885 + (maxplayers* 15) and cannot be changed while a map is running on a server. The number '885' in that formula can be altered by using the command line parameter 'num_edicts #', whereas the hash has to be replaced with a number greater than 885. This is commonly set to 8192 for Sven Co-op servers. If an entity has to be created, but no free edicts are available, the game will crash with the error ED_Alloc: No free edicts..

2 Triggering

Entities can trigger each other with different inputs. The following is a list of these inputs. This guide may refer to these at some points in order to explain things better, so make sure you remember them.

• Activator: The first entity in a trigger chain. E.g.: A player pressing a func_button, which then triggers further entities. Entities which make use of their activator, depending on their configuration, for example, are: game_text, env_fade or game_player_hurt. For all entities where a delay between them being triggered and them triggering their target is expected, the activator they pass on to their targets is, by default, replaced by themselves. This is to prevent cases of entities which have already been removed from the game being referenced, resulting in unwanted behavior. An activator can, in some cases, be referenced to using the special string !activator. This does not consistently apply everywhere. See the specific entity entries in this guide for whether a specific entity supports this or not.
• Caller: The previous entity in a trigger chain. E.g.: The aforementioned func_button triggers a multi_manager, hence the multi_manager's caller would be the func_button. A caller can, in some cases, be referenced to using the special string !caller. This does not consistently apply everywhere. See the specific entity entries in this guide for whether a specific entity supports this or not.
• Use-type: Tells the targeted entity what to do. This is not implemented consistently. An entity will only react according to the use-type if the exact behavior for the according use-type case has been explicitly written in the game's source code, which is not the case for every entity and use-type. The following explains all five use-types currently present in the game engine.
  • Off: Turn the targeted entity off.
  • On: Turn the targeted entity on.
  • Set: A specific value of the target entity, if it supports it, is set and the targeted entity may react accordingly.
  • Toggle: If the targeted entity is on, turn it off. If the targeted entity is off, turn it on.
  • Kill: Remove the targeted entity from the game.

• Value: A real number, which is used for different purposes, depending on triggering and targeted entity. E.g., a game_zone_player, when triggered, will trigger its 'out-counter' (which should be a game_counter entity) with use-type 'Set' and set the transmitted value to the amount of players outside of its collision hull. The game_counter will recognize the use-type 'Set' and set its current value to the one forwarded by the game_zone_player entity. Furthermore, the game_counter will then check if the new value matches its "Limit value" and trigger its target(s) in case that is true. A completely different usage, however, can, for example, be seen when a func_button triggers an entity. The func_button puts its delay before reset as the value, but does not allow use-type 'Set'. You can see the effect of this when triggering a multisource entity with a func_button. The multisource entity's state will only be 'unlocked' for as long as the func_button's delay before reset has not been reached. This is because the multisource entity knows the exact delay from when it was triggered by the func_button with its delay before reset being set as the transmitted value.

3 Wildcards

There is possibility to trigger multiple entities with same prefix at once, making it faster to target or killtarget them without using multi_manager or relays. Just write an entity name in the target field and add asterisk (*) at the end of string. Any entity that begins with that string will be targeted. Example: func_door target is action_*, so it will fire entities like action_door, action_wall, action_grunts e.t.c. You can do the same with kill-targeting entities.

4 Expected Default Behavior

Some default behaviour is to be expected from most entities, in which cases this guide will not specifically explain the according keyvalue(s) and/or spawnflag(s). Whenever an entity can have a target, it will usually mean that all entities by the name specified as the target will be fired. Same goes for kill-target, which will remove all targeted entities from the game. Whenever an entity allows 'Trigger-state' to be set, this guide should not be expected to explain what that means, as you should already have read about use-types above. This guide, for most of it, only explains things which work different from the normally to-be-expected default behaviour. I am not here to copy and paste the same basic keyvalues a thousand times for every entity, as this guide is written in pure HTML entirely, without any help from programs other than Notepad2. I also do not intend to make this a guide about mapping in general. It is mainly for reference on how specific entities work in Sven Co-op 4.5. Mapping experience withsome GoldSource mod is expected.

5 Special Targetnames

The game engine knows five special targetnames. Entities which are named with these are triggered with use-type 'Toggle' whenever the according player-event occurs. Activator and caller are set to the player who causes the event.

• game_playerkill: A player kills another player. Activator and caller are set to the player who killed.
• game_playerdie: A player dies. Activator and caller are set to the player who died.
• game_playerjoin: A player joins the game. Activator and caller are set to the joining player.
• game_playerleave: A player leaves the game. Activator and caller are set to the leaving player.
• game_playerspawn: A player spawns or respawns. Activator and caller are set to the spawning/respawning player.

On another note, entity names should never start with 0.