Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commitcc6939bf11

README.md

bodyFacing

Which way a character's body visibly faces, by the one rule every reader of that facing shares. Locomotion and LocomotionFull resolve the anchor they turn through here, and CameraRig.visibleForward reads the facing through here, so a follow camera binding behind a character reads the anchor the component turns, whichever component animates it and however the character's children are ordered (a body swapped in by setCharacter stands after the avatar's name label).

The rotation anchor is the topmost direct child of the entity the component sits on whose subtree holds the rigged skeleton, else that entity itself when it carries a Skeleton. Each component declares which way along the anchor the body faces: Locomotion.forward is a direction in the anchor's local frame ({0, 0, -1} by default, the -Z every composed avatar body faces along), and LocomotionFull.faceSign names the anchor's -Z (1) or +Z (-1).

How a body file is composed under the anchor so it faces the anchor's -Z, measured from its skeleton, is @builtin::modules.bodyFacing.

Exports

  • BodyFacing.COMPONENTS: { "Locomotion", "LocomotionFull" }, the components that turn a body, in the order a character carrying both reads them.
  • BodyFacing.isRigged(entityId) -> boolean: the entity carries a Skeleton whose rig has hydrated (bones present).
  • BodyFacing.body(entityId) -> string?: the skinned body, the entity itself when rigged, else its first rigged descendant.
  • BodyFacing.anchor(entityId) -> string?: the rotation anchor of the character the facing component sits on.
  • BodyFacing.heldAnchor(entityId) -> string?: the anchor as anchor resolves it, kept from one read to the next while it still stands as the entity or one of its direct children, and resolved again once it has gone, so a reader asking every frame walks the body's subtree once.
  • BodyFacing.declared(componentName, component) -> (x, y, z): the anchor-local direction a facing component declares.
  • BodyFacing.declaring(targetId) -> (id?, componentName?, component?): the subject or the nearest ancestor carrying a facing component.
  • BodyFacing.forward(targetId) -> (x?, y?, z?): the world-space direction the body faces, read through heldAnchor, nil when nothing up the chain turns the subject.
  • BodyFacing.source(targetId) -> string?: what forward reads the facing from (the declaring entity, the component, the anchor and the anchor-local direction it declares), as one key that changes when a facing component arrives or goes, when what it declares changes (Locomotion.forward, LocomotionFull.faceSign) or when a body stands up under the character, and holds while the body turns; nil when nothing up the chain turns the subject.
local BodyFacing = require("@builtin::systems.characterController.characterController.movement.bodyFacing")
local fx, fy, fz = BodyFacing.forward(characterId)