This article relates to the game "Portal 2". Click here for more information.
This article relates to the game "Team Fortress 2". Click here for more information.
This article relates to the game "Garry's Mod". Click here for more information.

trigger_catapult

From Valve Developer Community
Jump to: navigation, search

trigger_catapult is a brush entity available in the following Source Source games or engine branches:
Portal 2 Portal 2Team Fortress 2 Team Fortress 2 and Garry's Mod Garry's Mod. An entity named trigger_catapult is also available in Alien Swarm: Reactive Drop Alien Swarm: Reactive Drop, but it seems to be a different entity with different functionality.

It is used to launch the player or other objects into the air. Its ability to set an entity's flying direction or target, to consider their current velocity and – in the case of players – to supress their controls makes it a powerful tool to contol how they will fly and thus where they will land.

Portal 2 They are typically used for Aerial Faith Plates to accomplish a kind of Fling that doesn't necessarily require the player to use portals.

Configuration

The fling direction is determined by the keyvalues Launch target or Launch direction. The latter is ignored if the former is set. Other than that, the mapper can determine a minimum, a maximum and a direction that an entity's velocity must satisfy in order to be launched at all.

Warning.pngWarning:If an entity is launched with a speed of 0, the game crashes.

Launch target

// Squirrel function simulating a trigger_catapult with launch target
// trigger_catapult(launchedEntityHandle, targetVector, float)
::trigger_catapult <- function(ent, target, speed=450)
{
	local g = 600                          // sv_gravity
	local d = target - ent.GetOrigin()     // vector from start to target
	local t = d.Length() / speed           // seconds the flight will take
	local vz = d.z / t + 0.5 * g * t       // initial z-speed that we need
	local v = Vector(d.x / t, d.y / t, vz) // v.Length() is threshold base
	ent.SetVelocity(v)
}

The simplest configuration is to create or find an entity (e.g. info_target or anything else) whose origin is positioned at the location that the player or object should fly to, and to specify that entity's name in the Launch target keyvalue of the trigger_catapult.

With this set, the two speed keyvalues determine the flying height, where typically a higher speed flattens the flinging arc and a lower speed steepens it. The actual launch speed also varies slightly depending on where this trigger_catapult is touched (since you cannot treat every launch position equally). The target will be missed if the launched object is affected by forces other than gravity after launch.

If a Launch target is set and an object (that passes the filters) touches the trigger_catapult, the game calculates the time in which the object should reach the target by dividing the initial distance between the two by the appropriate speed keyvalue (which is why the game crashes if that speed happens to be zero): time = distance / speed. Based on this time, the game shoots the object in a direction such that it reaches the target in exactly the calculated time, as seen in the code on the right. The speed which the game wants to shoot the entity with is the base value for the eventual threshold check, see below. Anyway, that's why specifying a really low speed results in a very high launch speed upwards since a low speed means a long time before the object should reach the target.

Why?: If Use Exact Velocity is set to Yes and if a Launch target is specified, it may happen that the game prints "Catapult can't hit target! Add more speed!" in the console (with developer 1) even though more speed doesn't help the issue.

Launch direction

One can also leave the Launch target blank and instead set the Launch direction. In this case, the speed keyvalues truly represent the speed at which an object will be launched with, except if the Launch direction keyvalue is set to Up (exactly -90 0 0) where the launch speed is 1.5 times as much (this is not related to the Use Exact Velocity keyvalue). To reach a maximum height of h from the start height in the case of Up (-90 0 0), set the speed to sqrt(h) * 23.1.

In general, if an entity is launched at a speed of speed u/s and at an angle of pitch (0 to -90, where 0 means horizontal and -90 means up), then the launched object will reach its highest point in t = speed * sin(-pitch) / sv_gravity seconds, which lies t2 * sv_gravity / 2 units higher and t * speed * cos(pitch) units away (in the x-y-plane) from its launching point.

Velocity threshold

If Use Threshold Check is set to Yes, this trigger_catapult will only fling an entity if its velocity is at least speed * (1 - lowerThreshold) u/s but at most speed * (1 + upperThreshold) u/s, where speed is the velocity that the game would shoot the entity with. If no Launch target is set, it is equal to the appropriate speed keyvalue, otherwise it's what the game calculates, see the code above.
Portal 2: Community Edition If Use Absolute Threshold Check is set to Yes, the threshold keyvalues represent actual velocities.

In addition, the Entry Angle Tolerance can be used to limit the direction in which the velocity of an entity must point in order for it to be flung at all. If set to x, the entity is only flung if the angle between its entry velocity and the vector from the launch position to the target is at most cos-1(x), where x = 0 means at most 90° off, x = -1 means always (at most 180° off), see dot product.

Supress player controls

The Air Control Supression Time can be used to prevent a player from strafing out of an intended flinging arc. It disables a player's controls in mid-air for a fixed number of seconds after the launch. This effect doesn't end when they land, so a mapper may want to get this duration about right, if necessary by measuring it in-game (e.g. with host_timescale and script printl(Time())).
For a predictable flinging arc, this helps eliminate one disturbing factor but there are more to consider, for instance portal funneling, static obstacles, other unpredictably flying objects, trigger_push, gunfire, sv_maxvelocity (3500 u/s by default), etc.

Testing

If you compiled a map and you are unhappy with a configuration, you don't need to recompile to test a different one: Change the trigger_catapult's keyvalues in-game using ent_fire <trigger_catapult_name> addoutput "<keyvalue> <value>". If there is no name, use trigger_catapult as a name to target all of them. All changes done with ent_fire are discarded when the map changes or reloads.

In-game, the predicted flinging arcs can be viewed using the commands developer 1, ent_bbox trigger_catapult and ent_absbox trigger_catapult. Setting developer to ≥ 1 also prints debug information about ongoing threshold checks.

KeyValues

Player Speed (playerSpeed) <float>
Physics Object Speed (physicsSpeed) <float>
Speed at which to launch players / physics objects, respectively (u/sec). If a launch target is set, this speed refers only to the distance between start and target point. Setting it to 0 will crash the game on the next use!
Use Threshold Check (useThresholdCheck) <boolean>
If set to yes the player/object will only be catapulted if his/its speed is within the limits specified in the keyvalues for lower and upper threshold.
Entry Angle Tolerance (entryAngleTolerance) <float>
Flung object's velocity must be pointing this much at the target. Specify a value between [-1...1] 1 means exactly, 0 means within 180 degrees -1 means any angle is accepted. This is only used if Use Threshold Check is set to yes.
Use Exact Velocity (useExactVelocity) <boolean>
Try to fling exactly at the speed specified - this prevents the added upward velocity from a launch target.
Exact Solution Method (exactVelocityChoiceType) <choices>
Using exact velocity generates two correct solutions. Use this to force which one you choose.
  • 0 : Best
  • 1 : Solution One
  • 2 : Solution Two
Lower Threshold (lowerThreshold) <float>
Flung object must be within this percentage value in order to activate fling. The percentage specified is subtracted from the speed set in the keyvalue Player Speed. Specify a value between [0...1] (default is .15) This is only used if Use Threshold Check is set to yes.
Upper Threshold (upperThreshold) <float>
Flung object must be within this percentage value in order to activate fling. The percentage specified is added to the speed set in the keyvalue Player Speed. Specify a value between [0...1] (default is .30) This is only used if Use Threshold Check is set to yes.
Launch direction (launchDirection) <angle>
Direction to launch the player in. This keyvalue is ignored if Launch target is set.
Launch target (launchTarget) <targetname>
Entity to try to 'hit' when we're launched.
Only check velocity (onlyVelocityCheck) <boolean>
Only check velocity of the touching object - don't actually catapult it. Use in conjunction with OnCatapulted to create velocity checking triggers. Only works when Use Threshhold Check is enabled.
Apply angular impulse (applyAngularImpulse) <boolean>
If a random angular impulse should be applied to physics objects being catapulted.
Air Control Supression Time (AirCtrlSupressionTime) <float>
[Launch by target only!] If greater than zero, supress player aircontrol for this number (in seconds). If less than zero use the default (quarter second).
Note.pngNote:
  • The supression remains active even if the player has already landed.
  • This helps to get a predictable flinging arc but there may be more to consider, see above.
Use Absolute Threshold Check <boolean> (only in Portal 2: Community Edition)
If true, the threshold values represent actual velocities instead of a percentage

BaseTrigger:

Filter Name (filtername) <filter>
A filter entity to test potential activators against.
Start Disabled (StartDisabled) <boolean>
Stay dormant until activated (with theEnableinput).


Flags


BaseTrigger:
  •  [1] : Clients (Survivors, Special Infected, Tanks Left 4 Dead series)
  •  [2] : NPCs (Common Infected, Witches Left 4 Dead series)
  •  [8] : Physics Objects
  •  [16] : Only player ally NPCs
  •  [32] : Only clients in vehicles
  •  [64] : Everything (not including physics debris)
  •  [512] : Only clients *not* in vehicles
  •  [1024] : Physics debris
  •  [2048] : Only NPCs in vehicles (respects player ally flag)
  •  [4096] : Disallow Bots

Inputs


BaseTrigger:
Toggle
Toggles this trigger between enabled and disabled states.
Enable
Enable trigger
Disable
Disable trigger
TouchTest  (in all games since Source 2007)
Triggers either the OnTouching or OnNotTouching outputs for whether anything is touching this entity.
StartTouch  (in all games since Source 2007) !FGD
Behave as if the !caller entity had just entered the trigger volume. Accepts non-physical entities.
EndTouch  (in all games since Source 2007) !FGD
Behave as if !caller had just exited the trigger volume.
DisableAndEndTouch  (only in Source 2013 Multiplayer(Team Fortress 2))
Disables this trigger and calls EndTouch on all currently-touching entities.


Outputs

OnCatapulted
Fires when the object has been launched or would have been launched (if onlyVelocityCheck is set to Yes).

BaseTrigger:

OnStartTouch
Fired when a valid entity starts touching this trigger. !activator is whatever touches the trigger.
OnStartTouchAll
Fired when a valid entity starts touching this trigger, and no other entities are touching it. If there are any other entities touching the trigger when a new one begins to touch, only OnStartTouch will fire.
OnEndTouch
Fired when a valid entity stops touching this trigger.
Warning.pngWarning:This includes entities which are deleted while inside the trigger. In this case !activator will be invalid.
OnEndTouchAll
Fired when all valid entities stop touching this trigger.
OnTouching  (in all games since Source 2007)
Fired if something is currently touching this trigger when TouchTest is fired.
OnNotTouching  (in all games since Source 2007)
Fired if nothing is currently touching this trigger when TouchTest is fired.