Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit15ce14a4c1

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