Builtin Library
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 asanchorresolves 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 throughheldAnchor, nil when nothing up the chain turns the subject.BodyFacing.source(targetId) -> string?: whatforwardreads 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)