llPassTouches(integer pass)

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

When a script in the root prim has one of the touch events (touch_start, touch or touch_end) active, the whole object becomes touchable. However, when a child prim has at least one script that has a touch event active and that prim is touched, by default only that prim will receive the touch, and the root will not receive it. This function allows changing that default, so that both the root and the child can receive the touches, or so that the root won't receive them even if the child has no active touch events.

This function should be called from a script in a child prim; it has no effect if called from the root prim.

An integer value indicating whether to pass touches to the root.

A value of PASS_IF_NOT_HANDLED makes the root receive touches from the child prim the script is in, only if none of the scripts in that child has an active touch event. If there is one, the root won't receive touches; only the child will. This is the default value when no script in the child calls llPassTouches.

A value of PASS_ALWAYS makes the root receive touches from the child prim the script is in, even if a script in that child prim has an active touch event (in which case both will receive it).

A value of PASS_NEVER makes the root not receive touches from the child prim the script is in, regardless of the presence or absence of an active touch event in the child.

• The setting only takes place for the prim where the script is in; it doesn't affect any other prims.
• If there is an active touch event in the child, it will always receive touches, regardless of this setting. It only affects whether the root will receive touches.
• If the root prim has an active touch event, a touch cursor will be shown for all prims in the linkset, regardless of the setting of this function. In other words, a value of PASS_NEVER will not make the hand cursor disappear for the child prim the script is in, even if there's no active touch event in the child.
• This setting is NOT a prim property, it is per script. Deleting or stopping all scripts that changed it from default will cause the effect to cease, and the behaviour to revert to default.
  • 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 (PASS_NEVER has precedence over PASS_ALWAYS, which has precedence over PASS_IF_NOT_HANDLED).
• What does active mean in this case? Touch events are active only if the script is running and in a state that has a touch event. If the script stops running, or if the current state has no touch event, there will be no active touch event for that script.

llPassTouches(PASS_ALWAYS); // Enables touch passing for this prim.

llPassTouches(PASS_NEVER); // Disables touch passing.

// Disables touch passing if there's an active touch event;
// lets the root receive them if not:
llPassTouches(PASS_IF_NOT_HANDLED);

When this simple script is dropped into a child prim that has more scripts, one of them with a touch event, it will let the root know that it has been touched. Imagine, for example, a swing where the seat is a child prim, which has a script that activates a pose menu, and the root has a script that starts and stops swinging, but the seat where the pose menu is, is easier to touch than other prims. In that case, dropping this script into the seat will make both the swing script and the menu activate with a single touch of the seat.

Removing or stopping the script will make the effect disappear.

llPassTouches-example.lsl

default
{
    state_entry()
    {
        llPassTouches(PASS_ALWAYS);
    }
}

The following pair of scripts illustrates the behaviour of the different modes. It will toggle between active and inactive every five seconds, and it will report in chat who receives the touches.

This script goes in a child prim:

llPassTouches-behaviour-child.lsl

// Edit the following line to test the different modes
// (use PASS_IF_NOT_HANDLED, PASS_ALWAYS or PASS_NEVER depending
// on what you want to test):
integer Behaviour_to_test = PASS_IF_NOT_HANDLED;

default
{
    state_entry()
    {
        llPassTouches(Behaviour_to_test);
        llSetTimerEvent(5);
        state WithTouch;
    }
}

state WithTouch
{
    state_entry()
    {
        llSetText("This prim has an active touch_end event now.", <1,0,0>, 1);
    }

    touch_end(integer num_touchers)
    {
        llSay(0, "The child prim received the touch.");
    }

    timer()
    {
        state WithoutTouch;
    }
}

state WithoutTouch
{
    state_entry()
    {
        llSetText("This prim has no active touch events now.", <0.4,0.4,0.4>, 1);
    }

    timer()
    {
        state WithTouch;
    }
}

And this script goes in the root prim:

llPassTouches-behaviour-root.lsl

default
{
    touch_end(integer num_touchers)
    {
        llSay(0, "The root received a touch.");
    }
}

• Touch events: touch_start, touch, touch_end.
• llPassCollisions is similar but for collision events.
• PASS_IF_NOT_HANDLED, PASS_ALWAYS, PASS_NEVER constants.