SyncWithParticipantBone

Description

Reads the world (global) position and rotation of the specified bone on the specified participant's avatar via PlayerHandle.getHumanoidBonePosition and PlayerHandle.getHumanoidBoneRotation, then applies them to this item with the configured world-space offsets. Position offset is added to the bone's world position; rotation offset (Euler degrees) is pre-multiplied with the bone's world rotation. Typically placed under During State so the item follows the bone every frame, but also usable as a one-shot snapshot under On State Start / On State Exit. Silently no-ops if the participant is not present or the bone is unavailable on the avatar. Requires the MovableItem component on this item.

Parameters

Side effects

• Reads the participant's bone world transform via PARTICIPANTS[participantIndex].getHumanoidBonePosition(bone) and getHumanoidBoneRotation(bone).
• Writes the resulting (bonePos + posOffset, rotOffset · boneRot) back to this item's MovableItem transform. The change is networked to all players.
• Requires the item to have a MovableItem component on this item. Without it, the runtime logs a warning and the call is a no-op.
• Silently no-ops if PARTICIPANTS[participantIndex] is undefined, if the avatar exposes no humanoid skeleton (e.g., a non-humanoid Cluster avatar), or if the bone name doesn't resolve.
• No state keys are written, no signals fired, and $.groupState is untouched. The transform update is the only effect.
• When used under During State, the action runs every frame (~once per $.onUpdate), which is the only way to make the item track the participant smoothly.

Example

Make a "headlamp" item follow participant 1's head, pointed forward, offset slightly above and in front of the brow:

// Add to the Headlamp item, in the "During State" column of a state where the lamp is active
SyncWithParticipantBone(1, "Head", [0, 0.1, 0.15], [0, 0, 0]);

For a virtual-prop study where a tool sits in the participant's right hand:

// During State of the trial state where the tool is held
SyncWithParticipantBone(1, "RightHand", [0, 0, 0.05], [0, 0, 0]);

For a one-shot snapshot — e.g., capture where the participant's head was at trial start, then leave the item stationary:

// On State Start only (no During State entry)
SyncWithParticipantBone(1, "Head", [0, 0, 0], [0, 0, 0]);

Related

• AssignAvatarToParticipant(avatarID, participantIndex) — full-body avatar swap; this action is for attaching individual items to bones without changing the whole avatar.
• SetPosition(x, y, z) — for absolute positioning that doesn't track a bone.
• Reference → Variables → PARTICIPANTS — the PlayerHandle API that exposes getHumanoidBonePosition / getHumanoidBoneRotation.
• Assets/Doc/CCK-Types.d.ts — full HumanoidBone enum values.

Source

Assets/Doc/LUIDA-StateListeningItemScriptDoc.md

- **Description**: Reads the world (global) position and rotation of the specified bone on the specified participant's avatar via `PlayerHandle.getHumanoidBonePosition` and `PlayerHandle.getHumanoidBoneRotation`, then applies them to this item with the configured world-space offsets. Position offset is added to the bone's world position; rotation offset (Euler degrees) is pre-multiplied with the bone's world rotation. Typically placed under **During State** so the item follows the bone every frame, but also usable as a one-shot snapshot under **On State Start** / **On State Exit**. Silently no-ops if the participant is not present or the bone is unavailable on the avatar. **Requires the `MovableItem` component on this item.**
- **Parameters**:
  - `participantIndex`: `integer` (starts from 1)
  - `bone`: `string` — one of the `HumanoidBone` enum names (e.g. `Head`, `RightHand`, `Hips`). See `Asset/Doc/CCK-Types.d.ts` for the full list.
  - `posOffset`: `(x, y, z)` world-space offset in meters added to the bone position.
  - `rotOffset`: `(x, y, z)` world-space Euler offset in degrees, pre-multiplied with the bone rotation.