$nav
===== Function: llPassCollisions =====

<code lsl2>
llPassCollisions(integer pass)
</code>

Indicates whether a child prim in a linkset should let the root know that it has registered a collision.

When a running script in the root prim has one of the collision events ($lev[collision_start], $lev[collision], $lev[collision_end], $lev[land_collision_start], $lev[land_collision] or $lev[land_collision_end]) active, collisions in any prim of the linkset are registered by the root. As an exception, when a child prim has at least one script that has a collision event and that prim is collided, by default only that prim will register the collision, and the root will not register it. This function allows changing that default, so that //both// the root and the child can register the collisions, or so that the root won't register them even if the child has no active collision events.

It may be useful e.g. when the script in the root needs to detect whether the object was impacted, no matter where, but one specific prim needs to perform an additional action when it is impacted without excluding the root from doing its job. Or to exclude certain prims from passing collisions to the root, without the need for the root to filter them programmatically.

This function should be called from a script in a child prim, and it affects whether collisions in that child are passed to the root as well as registered by the child. It has no effect if called from the root prim.

===== Parameters =====

=== pass ===
An $lty[integer] value indicating whether to pass collisions to the root.

A value of $lct[PASS_IF_NOT_HANDLED] makes the root register collisions originated in the child prim the script is in, only if none of the scripts in that child has an active collision event. If there is one, the root won't register collisions; only the child will. This is the default value when no script in the child calls $fn[llPassCollisions].

A value of $lct[PASS_ALWAYS] makes the root register collisions from the child prim the script is in, even if a script in that child prim has an active collision event (in which case both will register it).

A value of $lct[PASS_NEVER] makes the root not register collisions from the child prim the script is in, regardless of the presence or absence of an active collision event in the child. 

===== Notes =====

  * For an object with $lfn[llVolumeDetect] set to $ct[TRUE], this setting has no effect. Only the scripts in the root will receive $ev[collision_start] and $ev[collision_end] events coming from any prim in the object, no other script in any other prim will, and no script in any prim will register $ev[collision] or $ev[land_`*] events.
  * If there is an active collision event in the child, it will always register collisions, regardless of this setting. It only affects whether the root will register collisions.
  * The setting only takes place for the prim where the script is in; it doesn't affect any other prims.
  * $perscript
    * If the same script calls this function several times, the one that was executed last prevails. If several scripts in the same prim call it, the one with the highest value takes precedence ($ct[PASS_NEVER] has precedence over $ct[PASS_ALWAYS], which has precedence over $ct[PASS_IF_NOT_HANDLED]).
  * What does //active// mean in this case? Collision events are //active// only if the script is running and in a state that has a collision event. If the script stops running, or if the current state has no collision event, there will be no active collision event for that script.


===== Short examples =====

<code lsl2>
llPassCollisions(PASS_ALWAYS); // Enables collision passing for this prim.

llPassCollisions(PASS_NEVER); // Disables collision passing for this prim.

// Disables collision passing if there's an
// active collision event in a script of this prim.
llPassCollisions(PASS_IF_NOT_HANDLED);
</code>

===== Complete examples =====

When this simple script is dropped into a child prim that has more scripts, one of them with a collision event, it will let the root know that it has been impacted even if the impact only affects the prim the script is in. If it is removed, and only this prim is impacted, the root will not register the impact.

<file lsl2 llPassCollisionss-example.lsl>
default
{
    state_entry()
    {
        llPassCollisions(PASS_ALWAYS);
    }
}
</file>

===== See also =====

  * Collision events: $lev[collision_start], $lev[collision], $lev[collision_end], $lev[land_collision_start], $lev[land_collision], $lev[land_collision_end].
  * $lfn[llPassTouches] is similar but for touch events.
  * $lfn[llCollisionFilter] restricts collisions to only the given UUID or name, or anything but the given UUID or name.
  * $lfn[llCollisionSound] sets the sound the prim should emit when collided.
  * $lct[PASS_IF_NOT_HANDLED], $lct[PASS_ALWAYS], $lct[PASS_NEVER] constants.