LogoLogo

Touch Bridge

Overview

NOTE

The touch bridge has been available since v123 and comes in the Obsidian box.

Basic usage

If you want others to touch your Obsidian and request a Remote HUD, put on the optional / touch bridge object found in your unpacked folder.

The touch bridge works similarly to sending a Remote HUD via the Send... menu, except that:

  • Others initiate the process of playing with your Obsidian.
  • After pairing, they do not appear added to Allowlist automatically, unlike when you use Send... to offer the Remote HUD yourself. As a result:
    • If you set your permissions Mode... to Let in (default since v123), then anyone will be able to play with your Obsidian through the touch bridge immediately after pairing (except those already in the Blocklist). If your Notify setting is enabled, you’ll get a notification in local chat with the [Blocklist] option.

      To unblock someone, Allowlist them. To unblock everyone, use Clear Cache in the ☰ menu of your Play HUD (see Clear Cache).

    • If you set your permissions Mode... to Ask, as soon as they attempt to play with your Obsidian via the Remote HUD they received, you’ll get a notification in your local chat with links such as [Allowlist] and [Blocklist].
    • If you set your permissions Mode... to Keep out, and Notify is set to enabled, you’ll get a notification in your local chat with the [Allowlist] option.

Remote HUDs are locked to one avatar after pairing has finished without a way to change that.

How to extend

Touch bridge is a modifiable prim that allows your own or other creators’ scripts to be added if desired and modify the behavior of the main script.

What the bridge does by itself

When someone touches it:

  • The owner: gets a short explanation that only they see.
  • Anyone else within 10 m of the touch bridge (of its wearer, when attached): the owner’s Obsidian offers them a Remote HUD. The distance can be changed with ~d, see Linkset data.
  • Further than that: they are told how much closer to get.
  • In a neighboring region: they get an IM asking them to come over, at most once every 30 seconds.

Each avatar can request a HUD once every 30 seconds. Receiving the HUD does not grant access by itself: it still obeys the owner’s Mode (Keep out / Ask / Let in) and their Allowlist and Blocklist.

Adding a script

  1. Detach the touch bridge and rez it in-world.
  2. Edit it and open its Contents tab.
  3. Drag your script, or the one given to you, into Contents, next to “touch bridge v1.0”.
  4. Take the touch bridge back into your inventory and wear that one.

Leave “touch bridge v1.0” in place, because nothing else can request a HUD.

Writing a script

Reacting to a reset

The touch bridge script resets whenever it starts or restarts, including when the touch bridge changes owner. A reset:

  • Turns processing on touch on (~e = "1").
  • Sets the distance of operation to 10 m (~d = "10").
  • Clears the bridge’s records of who touched it and who requested a HUD (the ~a|, ~i| and ~t| keys).

When it is done, the bridge sends "reset_done" (see below), so your script can apply its own settings again.

Reacting to a request

The bridge sends link messages on -89099 to the other scripts in its prim:

link_message(integer sender_num, integer num, string str, key id) {
  if (num == -89099) {
    if (str == "reset_done") {
      // the touch bridge script is done resetting
      // add your initial settings
    } else if (str == "hud_requested") {
      // id is the avatar the HUD was requested for
    }
  }
}
  • "hud_requested": the request went out to the owner’s Obsidian, not that the HUD was delivered. It is not sent when the 30-second limit blocked the request.
  • "reset_done": the touch bridge script is done resetting. Initialize or override the values according to your needs.

Replacing the touch behavior

The bridge handles touches only while the linkset data key ~e is "1", which is how the touch bridge is delivered. To decide yourself what a touch does, write "0" to it and ask the bridge for a HUD when you are ready:

reset() {
  llLinksetDataWrite("~e", "0"); // "0" turns the bridge's touch handling off, "1" back on
}
 
default {
  state_entry() {
    reset();
  }
 
  link_message(integer sender_num, integer num, string str, key id) {
    if (num == -89099) {
      if (str == "reset_done") {
        // the touch bridge script is done resetting
        reset();
      }
    }
  }
 
  touch_start(integer num_detected) {
    key toucher = llDetectedKey(0);
    if (toucher == llGetOwner()) return;
    // Your own rules or menu go here, then:
    llMessageLinked(LINK_THIS, -89099, "send_hud", toucher);
  }
}
  • The "send_hud" request works whether touch handling is on or off.
  • The bridge only sends a HUD to an avatar who touched it from within the ~d distance in the last 180 seconds. Requests for anyone else are ignored silently, so check the distance yourself if you want to tell the avatar to get closer.
    • The bridge keeps recording these touches while touch handling is off.
    • Touches from a neighboring region are never recorded.
  • The distance is checked when the avatar touches, not when your request arrives, so the avatar may have moved away in the meantime.
  • The 30-second limit still applies: if it is too soon, the avatar is told to wait and nothing is sent.
  • The bridge writes ~e only when it resets (see Reacting to a reset), for example when the owner changes, so listen for "reset_done" to apply your setting again.

Linkset data

  • ~e belongs to the bridge. Touch handling is on only while it is "1". You can override it to "0" to disable automatic sending of the Remote HUD.
  • ~d belongs to the bridge. It is the maximum distance in meters, as a string, from which an avatar can request the HUD ("10" by default). You can override it to values between 5 and 30; values outside that range are treated as 5 or 30. If you replace the touch behavior, use the same distance in your script, because the bridge ignores "send_hud" for avatars who touched from further away.
  • ~a|<avatar key> belongs to the bridge. It enforces the 30-second limit on HUD requests.
  • ~i|<avatar key> belongs to the bridge. It limits the IMs sent to avatars touching from a neighboring region.
  • ~t|<avatar key> belongs to the bridge and is protected with a password. It records who touched the bridge from within range, to prevent sending a HUD to a random person who never touched the prim.

Use other names for your own data, and do not call llLinksetDataReset(): it removes ~e and ~d, which turns touch handling off and sets the distance to 5 m until the bridge resets.

Restoring the default behavior

If you delete a script that replaced the touch behavior, the bridge keeps ignoring touches until it resets, for example when it changes owner. To switch it back on, add a script with the following to the touch bridge, then delete it again:

default {
  state_entry() {
    llLinksetDataWrite("~e", "1"); // restore default enable touch
    llLinksetDataWrite("~d", "10"); // restore default distance (in meters)
  }
}

You can also go back to an unmodified touch bridge from your Obsidian box.

Graph View

Backlinks