up_frame

The frame something standing in the world stands in: up against the gravity where it is (Physics.upAt, which the GravityField components shape), and the two directions across it that a walk, a heading or a camera's orbit is measured along. The built-in CharacterController walks across one and publishes it as its frame field; WASDInput, MovementState, Locomotion and LocomotionFull read the controller's; the orbital_follow and third_person_follow cameras orbit and level themselves in one of their own. Positions stay in world space, and the module keeps no state of its own: something that moves holds its frame and hands it back each update.

local Frame = require("@builtin::modules.up_frame")
frame = Frame.follow(frame, p.x, p.y, p.z)               -- kept from one update to the next
local wx, wy, wz = Frame.toWorld(frame, dx, 0, dz)       -- a step across the ground, in world space

Exports

• Frame.at(x, y, z, groups?): the frame at a point, the world turned the shortest way that carries +Y onto the up there. The world's own frame wherever gravity pulls down -Y.
• Frame.follow(frame, x, y, z, groups?): the frame something moving keeps. While a GravityField acts it is frame carried onto the up at the point, so a heading held across it walks a straight line all the way round a planet, the far side included; where none acts it is the frame of the world's gravity. Returns the frame and the Physics.gravityFieldsAt read at the point.
• Frame.transport(frame, ux, uy, uz): a frame carried onto a new up by the shortest turn from its own.
• Frame.standing(entity): the frame a CharacterController walks its entity across (its frame), or the frame at the entity's position for an entity with none: what the controller's inputX / inputZ and velocityX / velocityZ run along.
• Frame.fromUp(ux, uy, uz), Frame.fromRotation(qx, qy, qz, qw), Frame.world(), Frame.isWorld(f): a frame from an up or from a rotation, the world's own, and whether a frame is the world's.
• Frame.toWorld(f, lx, ly, lz), Frame.toLocal(f, wx, wy, wz): a vector along the frame's X, up and Z in world space, and a world vector along the frame's axes.
• Frame.above(f, x, y, z, ly): the point ly along the frame's up from a point.
• Frame.lookAt(f, fx, fy, fz, tx, ty, tz): the rotation that looks from one point at another with the frame's up as the view's up, for a camera kept level with the ground a character stands on.

A frame is { x, up, z, rotation }: its three unit axes in world space, and the rotation carrying the world's axes onto them.