Trigger catapult

trigger_catapult is a brush entity available in Portal 2, Team Fortress 2, and Garry's Mod.

An entity named trigger_catapult is also available in Alien Swarm: Reactive Drop, but it seems to be a different entity with different functionality.

Entity description

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.

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

• The simplest way to configure a trigger_catapult is to only set the Launch target keyvalue to the name of an info_target which is positioned at the location that the player or object should fly to. With this set, the Launch direction keyvalue is ignored and 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 and direction vary depending on where this trigger_catapult is touched since the target must be reached in all cases, which couldn't be achieved if every launch position was treated equally. The target will be missed if the velocity is changed after the launch, except by gravity.

If a Launch target is set and an object to be launched 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. The speed which the game wants to shoot the entity with is the base value for the eventual threshold check, see below. Nevertheless, 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.

• 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). For a maximum height h in the case of Up, 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 t² * sv_gravity / 2 units higher and t * speed * cos(pitch) units away (in the x-y-plane) from its launching point.

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 keyvalue Player Speed or Physics Object Speed respectively.

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 if they landed earlier, so a mapper may want to get this duration right 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.

In-game, the predicted flinging arcs can be viewed using the commands developer 1, ent_bbox trigger_catapult and ent_absbox trigger_catapult and be manipulated using commands such as ent_fire trigger_catapult addoutput "playerSpeed 450". Setting developer to ≥ 1 also prints debug information about ongoing threshold checks.

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.

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:

• 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 ([todo internal name (i)]) <boolean> (only in )

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

Everything (not including physics debris) : [64] Clients (Survivors, Special Infected, Tanks ) : [1] Only clients in vehicles : [32] Only clients *not* in vehicles : [512] Disallow Bots (removed since ) : [4096] NPCs (Common Infected, Witches ) : [2] Only player ally NPCs : [16] Only NPCs in vehicles (respects player ally flag) : [2048] Physics Objects (not including physics debris) : [8] Physics debris (include also physics debris) : [1024] Pushables (Passes entities with classname func_pushable) : [4]  Deprecated. Equivalent to using Everything + filter_activator_class that filters func_pushable.

Inputs

BaseTrigger

Toggle Toggles this trigger between enabled and disabled states. Enable Enable trigger Disable Disable trigger TouchTest  (in all games since ) Triggers either the OnTouching or OnNotTouching outputs for whether anything is touching this entity. Bug:Sleeping prop_physics will never fire "OnTouching". Also applies to entities using prop_physics as base.  (tested in: ) StartTouch  (in all games since ) !FGD Behave as if the !caller entity had just entered the trigger volume. Accepts non-physical entities. EndTouch  (in all games since ) !FGD Behave as if !caller had just exited the trigger volume. DisableAndEndTouch  (only in ) 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 !activator = entity that caused this output !caller = this entity Fired when a valid entity starts touching this trigger. OnStartTouchAll !activator = entity that caused this output !caller = this entity 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 !activator = entity that caused this output !caller = this entity Fired when a valid entity stops touching this trigger. Note:Will also fire for entities touching it when trigger is disabled via Disable input Warning:This includes entities which are deleted while inside the trigger. In this case !activator will be invalid. Warning:OnEndTouch can fire before OnStartTouch under certain circumstances[How?] where both are fired on the same tick and each have the same delay. Fix:Add a slight delay to OnEndTouch. OnEndTouchAll !activator = entity that caused this output !caller = this entity Fired when all valid entities stop touching this trigger. OnTouching  (in all games since ) !activator = !caller = this entity Fired if something is currently touching this trigger when TouchTest is fired. OnNotTouching  (in all games since ) !activator = !caller = this entity Fired if nothing is currently touching this trigger when TouchTest is fired.