Ledge and wall probes for climbKit: where a character standing at `feet` and facing `dir` can pull itself up to, whether the wall in front of it is climbable, whether a capsule fits somewhere, and the mantle path between two points. Pure functions over the physics world's colliders, no state, usable from any mover (a player, an NPC, a test) in edit or play.
excludeList(selfId: string?, extra: { string }?) → void
| arg | type | description |
|---|
| selfId | string? | |
| extra | { string }? | |
castOptions(selfId: string?) → any
| arg | type | description |
|---|
| selfId | string? | |
addClimbRule(name: string, rule: ClimbRule) → void
Register a climb rule under `name` (replacing one of the same name). A rule is called as `rule(entityId, hit)` for a surface whose entity chain carries no `climbable` attribute, where `hit` holds the ray's `point`, `normal` and `distance` when there is one; it answers true (climbable), false (not climbable, stop asking) or nil (no opinion, ask the next rule). Rules run in the order they were added.
| arg | type | description |
|---|
| name | string | |
| rule | ClimbRule | |
removeClimbRule(name: string) → void
Remove the climb rule registered under `name`, if any.
| arg | type | description |
|---|
| name | string | |
hasClimbRule(name: string) → boolean
Whether a climb rule is registered under `name`.
| arg | type | description |
|---|
| name | string | |
suspendClimbRules( ) → void
Take every registered climb rule out for a while (a test that checks climbKit's own behaviour, a scene that wants marked surfaces only) and answer a function that puts them back as they were.
isClimbable(entityId: string?, hit: ClimbHit?) → boolean
Whether an entity is climbable. The attribute `climbable` on the entity or the nearest entity above it that carries one decides first: true is climbable, false is never climbable (so a wall made of many colliders is marked once on its root, and one part of it can opt out). With no attribute up the chain, the registered climb rules decide, given the surface `hit` (point, normal, distance) when the caller has one. With no rule saying yes, it is not climbable.
| arg | type | description |
|---|
| entityId | string? | |
| hit | ClimbHit? | |
wallRay(feet: Vec, dirX: number, dirZ: number, atHeight: number, distance: number, selfId: string?, maxNormalY: number?, exclude: { string }?) → WallHit
Cast one horizontal ray from `height` above the feet along `dir`. Answers the first surface steeper than `maxNormalY` (a wall rather than a floor or a ceiling), with whether it is climbable.
| arg | type | description |
|---|
| feet | Vec | |
| dirX | number | |
| dirZ | number | |
| atHeight | number | |
| distance | number | |
| selfId | string? | |
| maxNormalY | number? | |
| exclude | { string }? | |
wallAhead(feet: Vec, dirX: number, dirZ: number, height: number, distance: number, selfId: string?, exclude: { string }?) → WallHit
The wall in front of a character: rays at 35%, 55% and 85% of its height, nearest steep hit within `distance` of its axis. nil when nothing stands in front.
| arg | type | description |
|---|
| feet | Vec | |
| dirX | number | |
| dirZ | number | |
| height | number | |
| distance | number | |
| selfId | string? | |
| exclude | { string }? | |
fits(feet: Vec, height: number, radius: number, lift: number?, selfId: string?, exclude: { string }?) → boolean
Whether a standing capsule of `height` and `radius` fits with its feet at `feet`, lifted `lift` off the ground it stands on. True when it overlaps nothing.
| arg | type | description |
|---|
| feet | Vec | |
| height | number | |
| radius | number | |
| lift | number? | |
| selfId | string? | |
| exclude | { string }? | |
pathClear(feet: Vec, delta: Vec, height: number, radius: number, selfId: string?, exclude: { string }?) → boolean
Sweep a standing capsule (feet at `feet`) along `delta`. True when the whole path is clear.
| arg | type | description |
|---|
| feet | Vec | |
| delta | Vec | |
| height | number | |
| radius | number | |
| selfId | string? | |
| exclude | { string }? | |
slopeLift(radius: number, ny: number) → number
How far a capsule standing on ground of normal-y `ny` has to be raised so
its lower cap clears the slope it stands on.
| arg | type | description |
|---|
| radius | number | |
| ny | number | |
findLedge(o: LedgeOpts) → void
Find a ledge in front of a character it can pull itself up onto. Casts down a row of columns ahead of it, from `reach` above its feet, for the first top it can stand on (no steeper than `maxTopSlope` degrees), then checks that the top is between `minHeight` and `reach` above the feet, that the character fits standing on it, and that the way up and over is clear. Answers the ledge (top point, landing feet position, the point it rises to before moving over, height) or nil and the reason.
| arg | type | description |
|---|
| o | LedgeOpts | |
mantlePoint(start: Vec, risen: Vec, landing: Vec, t: number, split: number?) → Vec
The feet position along a mantle at progress `t` (0..1): rising straight up for the first `split` of it, then over and onto the landing, eased at both ends.
| arg | type | description |
|---|
| start | Vec | |
| risen | Vec | |
| landing | Vec | |
| t | number | |
| split | number? | |
ease(x: number) → number
| arg | type | description |
|---|
| x | number | |
mantleDuration(height: number, reach: number, minTime: number, maxTime: number) → number
How long a mantle of `height` takes, between `minTime` and `maxTime` seconds scaled by the height against `reach`.
| arg | type | description |
|---|
| height | number | |
| reach | number | |
| minTime | number | |
| maxTime | number | |
groundBelow(p: Vec, above: number, depth: number, selfId: string?, exclude: { string }?) → any
The ground under a point: a ray down from `above` metres over it for `depth` metres. Answers the hit or nil.
| arg | type | description |
|---|
| p | Vec | |
| above | number | |
| depth | number | |
| selfId | string? | |
| exclude | { string }? | |
applyMantleOpts(o: LedgeOpts, opts: { minHeight: number?, maxHeight: number?, probeDistance: number?, skipRiseCheck: boolean? }?) → LedgeOpts
Apply a caller's one-call widening of a mantle search (`tryMantle`'s `opts`) to ledge options `o`, clamped: `minHeight` to -1..reach, `maxHeight` to 0..reach, `probeDistance` to 0.1..2 m; NaN and infinite values are ignored. `skipRiseCheck` skips the room-straight-above check only for a rise of at most 0.3 m (a step across from a rope top whose head sits just under its anchor beam); a higher rise is still checked. Answers `o`.
| arg | type | description |
|---|
| o | LedgeOpts | |
| opts | { minHeight: number?, maxHeight: number?, probeDistance: number?, skipRiseCheck: boolean? }? | |