physics.module
This package holds more than this page lists. See all of its files in its world.
README.md
characters
The bodies characters meet one another as. A CharacterController moves by
sweeping its capsule against colliders, and this module stands every other
character in those sweeps' way. Every entity carrying a CharacterController is an
upright capsule standing on its feet, radius round and height tall, where
its entity stands, and the wall pass (physics.walls) sweeps against those
capsules beside the colliders: a character walking into another stops a skin
short of it, slides the rest of its walk around it, and reads blocked when
the other refuses the walk.
The push rule
- A walk never moves another character. Each character moves itself alone, so the bodies meet the same way on every peer: each peer moves the characters it owns against where it sees the others, a remote player's body among them.
- Two characters that overlap (placed into one another, a body the network
shows a frame late, two spawned at one point) move apart at no more than
the speed the controller gives (
apart), each taking half the overlap. A pair pressed together rests a skin apart; an overlapped pair comes apart over a few frames without either being thrown, and never through a wall. - A character gives way to no body moving into it. That body is the one to stop, by its own sweep on the peer that moves it, so a player walking into a standing one never drives it along, however late each peer sees the other.
- Two characters at the very same point come apart along the frame's X, the one whose entity id sorts first towards +X, which every peer reads alike.
- Only bodies that share some height meet: a character jumping over another passes above it, and a character coming down onto another's head is moved off it to the side.
Who meets whom
Each character carries a contactTag ("character" by default). Two
characters whose tags the world's contact filter answers "ignore" or
"sensor" pass through each other:
Physics.setContactFilter("character", "character", "ignore") -- nobody blocks anybody
entity(ghostId).component.get("CharacterController").contactTag = "ghost"
Physics.setContactFilter("ghost", "character", "ignore") -- the ghost walks through people
Physics.setContactFilter("redTeam", "redTeam", "ignore") -- teammates pass, foes block
A character never meets itself, a character parented under it, or one it is
parented under.
A character is a body while its entity is active and its CharacterController
enabled: one whose entity is set inactive (entity(id):setActive(false)) or
whose controller is disabled (controller.enabled = false) stands in nobody's
way until it is switched back on.
Exports
M.DEFAULT_TAG:"character", the tag a character meets others by when content names no other.M.passes(tagA: string, tagB: string) -> boolean: whether the contact filter lets two characters with those tags pass through each other.M.near(x, y, z, reach, radius, selfId, frame?) -> { Body }: the other characters withinreachof touching the characterselfId, with their feet, capsule and tag, as one read a step's sweeps share. Every character's body is read from its entity once a frame.M.placed(selfId, x, y, z): states where a character put its feet once it has moved itself. The bodies are read once a frame; the characters moving after it in the same frame meet it where it now stands.M.sweep(near, x, y, z, dirX, dirZ, distance, height, radius, frame?, bottom?) -> hit?: the first character innearthe body's sweep along(dirX, dirZ)reaches withindistance, as a hit table{ entityId, point, normal, distance, startedInside, character = true }. A character the body overlaps already stands in the way only of a walk further into it.M.apart(x, y, z, height, radius, selfId, maxStep, frame?, near?) -> (stepX, stepZ): the step across the frame, at mostmaxSteplong, that moves the character half of each overlap away from the characters it overlaps.
Usage
local Characters = require("@builtin::systems.characterController.characterController.physics.characters")
local near = Characters.near(px, py, pz, 0.5, 0.3, selfId)
local hit = Characters.sweep(near, px, py, pz, 1, 0, 0.5, 1.8, 0.3)
if hit then print("walks into", hit.entityId, "after", hit.distance) end