Log inGet started
Package

physics.module

Newest version

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), its carry and the frame's dt keeps 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 }, turn the body's turn about up as a quaternion, v the simulation's velocity for the body at the point (linear plus spin), or the displacement over dt for 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's carry included. 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 along up the surface a cast met stands drawn above the point the cast met it at; Ground.cast measures the ground's distance to the drawn surface with it.
  • M.turned(turn, r) -> Quat — the rotation r turned by turn in 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