physics.module
This package holds more than this page lists. See all of its files in its world.
README.md
platform
The body a character stands on, and how that body moves the character. A character standing on a body that moves or turns (a lift, a moving platform, a turntable, a raft, a ship's deck) is carried with it: the point under its feet goes where the body takes it, and it turns with the body's turn about up. Kinematic bodies a script moves, dynamic bodies the simulation moves and transforms something animates carry it alike. Pure helpers.
Poses are read where the frame draws them (Physics.drawnPose), so a
character carried by them stays in step with the platform on screen at any
frame rate and physics tick rate. A ride keeps how fast its body moved the
feet on each frame of its last tenth of a second, and of at least its last
six frames (trail): averaged, that is
how fast a kinematic body or an animated transform was carrying the character
when it leaves.
Exports
M.pose(entityId) -> (x, y, z, rotation)?— where an entity is drawn this frame and how it is turned, in world space.M.hold(entityId, from?, carry?, dt?) -> Ride?— the body a character stands on with the pose it is drawn at now. Hold it after the character is placed each frame; passing the ride the frame began on (from), itscarryand the frame'sdtkeeps the ride's trail going on the same body.M.carry(ride, x, y, z, up, dt?) -> Carry?— how that body moved the point(x, y, z)since the ride was held, and how fast it moves it this frame:{ entityId, dx, dy, dz, turn, moved, vx, vy, vz },turnthe body's turn aboutupas a quaternion,vthe simulation's velocity for the body at the point (linear plus spin), or the displacement overdtfor an entity under no body. nil with no ride or when its body is gone.M.velocityAt(ride, carry, dt) -> (vx, vy, vz)— how fast the body moves the feet: a dynamic body's velocity there this frame, else the velocity averaged over the ride's trail, this frame'scarryincluded. What a character keeps as momentum when it leaves the body.M.steer(vx, vz, walkX, walkZ, lerp, keptX, keptZ) -> (vx, vz)— air control for a character carrying the motion it kept from a body it left: the velocity steers toward that motion plus the walk asked for, so with no walk asked it goes on moving with the body it left.M.keptPast(keptX, keptZ, vx, vz) -> (keptX, keptZ)— the part of a kept motion a wall leaves once it cut the step to the velocity(vx, vz): none for a wall met head on, the part along a wall slid along.M.drawnRise(hit, up) -> number— how far alongupthe surface a cast met stands drawn above the point the cast met it at;Ground.castmeasures the ground's distance to the drawn surface with it.M.turned(turn, r) -> Quat— the rotationrturned byturnin world space.
Usage
local Platform = require("@builtin::systems.characterController.characterController.physics.platform")
-- each frame, before moving the character
local carry = Platform.carry(ride, px, py, pz, up, dt)
if carry then px, py, pz = px + carry.dx, py + carry.dy, pz + carry.dz end
-- ... walk, cast for ground, place the character ...
ride = if grounded then Platform.hold(groundHit.entityId, ride, carry, dt) else nil