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

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 within reach of touching the character selfId, 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 in near the body's sweep along (dirX, dirZ) reaches within distance, 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 most maxStep long, 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