Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(physics): character controller honors skinWidth/maxSlides/snapLength/slideOnCeiling

esenginebe3ed49821dd
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 4fa820a85..972a206ae 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4254,7 +4254,7 @@ _physics_hasJoint: (entityId: number) => number
_physics_hasMouseJoint: () => number
_physics_init: (gx: number, gy: number, timestep: number, substeps: number, contactHertz: number, contactDampingRatio: number, contactSpeed: number) => void
_physics_isAwake: (entityId: number) => number
-_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number) => number
+_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number, skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number) => number
_physics_overlapAABB: (minX: number, minY: number, maxX: number, maxY: number, maskBits: number) => number
_physics_overlapCircle: (centerX: number, centerY: number, radius: number, maskBits: number) => number
_physics_raycast: (originX: number, originY: number, dirX: number, dirY: number, maxDistance: number, maskBits: number) => number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 1c38b6b4b..e23fb6498 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4249,7 +4249,7 @@ _physics_hasJoint: (entityId: number) => number
_physics_hasMouseJoint: () => number
_physics_init: (gx: number, gy: number, timestep: number, substeps: number, contactHertz: number, contactDampingRatio: number, contactSpeed: number) => void
_physics_isAwake: (entityId: number) => number
-_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number) => number
+_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number, skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number) => number
_physics_overlapAABB: (minX: number, minY: number, maxX: number, maxY: number, maskBits: number) => number
_physics_overlapCircle: (centerX: number, centerY: number, radius: number, maskBits: number) => number
_physics_raycast: (originX: number, originY: number, dirX: number, dirY: number, maxDistance: number, maskBits: number) => number
diff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.md
index a7aa088c4..2bcf88515 100644
--- a/sdk/etc/physics.api.md
+++ b/sdk/etc/physics.api.md
@@ -292,7 +292,7 @@ getRevoluteMotorTorque: (entity: Entity) => number
getWheelJointMotorTorque: (entity: Entity) => number
hasMouseJoint: () => boolean
isAwake: (entity: Entity) => boolean
-moveCharacter: (pos: Vec2, c1: Vec2, c2: Vec2, radius: number, velocity: Vec2, dt: number, up: Vec2, floorCos: number, maskBits: number, self: Entity, ppu?: number) => MoverResult | null
+moveCharacter: (pos: Vec2, c1: Vec2, c2: Vec2, radius: number, velocity: Vec2, dt: number, up: Vec2, floorCos: number, maskBits: number, self: Entity, skinWidth?: number, maxSlides?: number, snapLength?: number, slideOnCeiling?: boolean, ppu?: number) => MoverResult | null
overlapAABB: (min: Vec2, max: Vec2, maskBits?: number, ppu?: number) => Entity[]
overlapCircle: (center: Vec2, radius: number, maskBits?: number, ppu?: number) => Entity[]
raycast: (origin: Vec2, direction: Vec2, maxDistance: number, maskBits?: number, ppu?: number) => RaycastHit[]
@@ -462,7 +462,7 @@ _physics_hasJoint: (entityId: number) => number
_physics_hasMouseJoint: () => number
_physics_init: (gx: number, gy: number, timestep: number, substeps: number, contactHertz: number, contactDampingRatio: number, contactSpeed: number) => void
_physics_isAwake: (entityId: number) => number
-_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number) => number
+_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number, skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number) => number
_physics_overlapAABB: (minX: number, minY: number, maxX: number, maxY: number, maskBits: number) => number
_physics_overlapCircle: (centerX: number, centerY: number, radius: number, maskBits: number) => number
_physics_raycast: (originX: number, originY: number, dirX: number, dirY: number, maxDistance: number, maskBits: number) => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8a1ea1ce5..f66fd6640 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4256,7 +4256,7 @@ _physics_hasJoint: (entityId: number) => number
_physics_hasMouseJoint: () => number
_physics_init: (gx: number, gy: number, timestep: number, substeps: number, contactHertz: number, contactDampingRatio: number, contactSpeed: number) => void
_physics_isAwake: (entityId: number) => number
-_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number) => number
+_physics_moveCharacter: (px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number, radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number, maskBits: number, selfEntity: number, skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number) => number
_physics_overlapAABB: (minX: number, minY: number, maxX: number, maxY: number, maskBits: number) => number
_physics_overlapCircle: (centerX: number, centerY: number, radius: number, maskBits: number) => number
_physics_raycast: (originX: number, originY: number, dirX: number, dirY: number, maxDistance: number, maskBits: number) => number
diff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.ts
index bf21339fe..52b14a20c 100644
--- a/sdk/src/physics/CharacterController.ts
+++ b/sdk/src/physics/CharacterController.ts
@@ -311,7 +311,9 @@ export function registerCharacterControllerSystem(app: App): void {
const r = physics.moveCharacter(
transform.position, mover.c1, mover.c2, mover.radius,
cc.velocity, dt, cc.up, Math.cos(cc.floorMaxAngle),
- cc.maskBits, entity, ppu,
+ cc.maskBits, entity,
+ cc.skinWidth, cc.maxSlides, cc.snapLength, cc.slideOnCeiling,
+ ppu,
);
if (!r) continue;
diff --git a/sdk/src/physics/Physics.ts b/sdk/src/physics/Physics.ts
index 00702f739..6002fb45a 100644
--- a/sdk/src/physics/Physics.ts
+++ b/sdk/src/physics/Physics.ts
@@ -263,7 +263,9 @@ export class PhysicsAPI {
moveCharacter(
pos: Vec2, c1: Vec2, c2: Vec2, radius: number,
velocity: Vec2, dt: number, up: Vec2, floorCos: number,
- maskBits: number, self: Entity, ppu = this.ppu_,
+ maskBits: number, self: Entity,
+ skinWidth = 0, maxSlides = 5, snapLength = 0, slideOnCeiling = true,
+ ppu = this.ppu_,
): MoverResult | null {
const invPpu = 1 / ppu;
const ok = this.module_._physics_moveCharacter(
@@ -271,6 +273,7 @@ export class PhysicsAPI {
c1.x * invPpu, c1.y * invPpu, c2.x * invPpu, c2.y * invPpu, radius * invPpu,
velocity.x * invPpu, velocity.y * invPpu, dt,
up.x, up.y, floorCos, maskBits, self >>> 0,
+ skinWidth * invPpu, maxSlides, snapLength * invPpu, slideOnCeiling ? 1 : 0,
);
if (!ok) return null;
const base = this.module_._physics_getMoveCharacterBuffer() >> 2;
diff --git a/sdk/src/physics/PhysicsModuleLoader.ts b/sdk/src/physics/PhysicsModuleLoader.ts
index 5e0288516..1b1d62ff4 100644
--- a/sdk/src/physics/PhysicsModuleLoader.ts
+++ b/sdk/src/physics/PhysicsModuleLoader.ts
@@ -162,7 +162,8 @@ export interface PhysicsWasmModule {
_physics_moveCharacter(px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number,
radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number,
- maskBits: number, selfEntity: number): number;
+ maskBits: number, selfEntity: number,
+ skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number): number;
_physics_getMoveCharacterBuffer(): number;
_physics_overlapAABB(minX: number, minY: number, maxX: number, maxY: number, maskBits: number): number;
diff --git a/sdk/tests/mover-smoke.mjs b/sdk/tests/mover-smoke.mjs
index 32392fa19..a6f5af3ca 100644
--- a/sdk/tests/mover-smoke.mjs
+++ b/sdk/tests/mover-smoke.mjs
@@ -1,6 +1,7 @@
// Headless validation of the native character mover (physics_moveCharacter).
-// Loads the built physics wasm directly, builds a static ground, and checks that a
-// resting character slides horizontally (the wedge bug) and a falling one lands.
+// Loads the built physics wasm directly, builds static geometry, and checks the
+// resting/wedge/landing behavior plus the skin-width, floor-snap, and ceiling
+// options wired through from the CharacterController component.
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
@@ -12,10 +13,13 @@ const wasmBinary = readFileSync(path.join(wasmDir, 'physics.wasm'));
const m = await factory({ wasmBinary });
// Static ground: box 8×0.4 m centered at (0,-2.5) → top surface at y=-2.3.
-const GROUND = 2, SELF = 9;
+const GROUND = 2, CEILING = 3, SELF = 9;
m._physics_init(0, -9.81, 1 / 60, 4, 30, 10, 3);
m._physics_createBody(GROUND, 0 /*static*/, 0, -2.5, 0, 1, 0, 0, 0, 0);
m._physics_addBoxShape(GROUND, 4.0, 0.2, 0, 0, 0, 1, 0.3, 0, 0, /*cat*/1, /*mask*/0xffff);
+// Static ceiling: box 8×0.4 m centered at (0,2.5) → bottom surface at y=2.3.
+m._physics_createBody(CEILING, 0, 0, 2.5, 0, 1, 0, 0, 0, 0);
+m._physics_addBoxShape(CEILING, 4.0, 0.2, 0, 0, 0, 1, 0.3, 0, 0, 1, 0xffff);
const buf = () => {
const b = m._physics_getMoveCharacterBuffer() >> 2;
@@ -23,8 +27,10 @@ const buf = () => {
return { dx: h[b], dy: h[b + 1], vx: h[b + 2], vy: h[b + 3], floor: h[b + 4], wall: h[b + 5], ceil: h[b + 6] };
};
// capsule from a 0.16×0.24 box: spine ±0.08 on Y, radius 0.16
-const move = (py, vx, vy) => {
- const ok = m._physics_moveCharacter(0, py, 0, 0.08, 0, -0.08, 0.16, vx, vy, 1 / 60, 0, 1, Math.cos(Math.PI / 4), 0xfffd, SELF);
+const move = (py, vx, vy, opts = {}) => {
+ const { skin = 0, maxSlides = 5, snap = 0, slideCeil = 1, px = 0 } = opts;
+ const ok = m._physics_moveCharacter(px, py, 0, 0.08, 0, -0.08, 0.16, vx, vy, 1 / 60, 0, 1,
+ Math.cos(Math.PI / 4), 0xfffd, SELF, skin, maxSlides, snap, slideCeil);
return ok ? buf() : null;
};
@@ -56,5 +62,36 @@ check('fall lands and grounds', grounded, `grounded=${grounded}`);
check('rests at the surface', Math.abs(py - -2.06) < 0.05, `center=${py.toFixed(3)} (want ≈-2.06)`);
check('does not sink through', py > -2.35, `center=${py.toFixed(3)} (floor top ~-2.30)`);
+// 4) skinWidth keeps a margin off surfaces: a resting character with skin>0 is
+// pushed up out of the floor by ~skin (its inflated radius overlaps otherwise).
+const skinned = move(-2.06, 0, 0, { skin: 0.1 });
+check('skinWidth lifts the character off the floor', skinned && skinned.dy > 0.05,
+ `dy=${skinned?.dy.toFixed(4)} (want >0.05 ≈ skin 0.1)`);
+const noSkin = move(-2.06, 0, 0, { skin: 0 });
+check('no skin: rests flush', noSkin && Math.abs(noSkin.dy) < 0.02, `dy=${noSkin?.dy.toFixed(4)}`);
+
+// 5) Floor snap: a character hovering 0.16m over the floor and not rising sticks
+// to it when snapLength reaches, and floats free without it (launch-off-ledge).
+const noSnap = move(-1.9, 2, -0.5, { snap: 0 });
+check('without snap: floats over the gap', noSnap && noSnap.floor === 0, `floor=${noSnap?.floor}`);
+const snapped = move(-1.9, 2, -0.5, { snap: 0.3 });
+check('snap sticks to the floor within reach', snapped && snapped.floor === 1, `floor=${snapped?.floor}`);
+check('snap pulls the character down', snapped && snapped.dy < -0.05, `dy=${snapped?.dy.toFixed(4)}`);
+// Snapping must not fire while rising (jumping away from the floor).
+const rising = move(-1.9, 2, 3, { snap: 0.3 });
+check('snap does not fire while rising', rising && rising.floor === 0, `floor=${rising?.floor}`);
+
+// 6) Ceiling: touching it while moving up is detected, and the upward velocity is
+// clipped (a flat ceiling stops the rise regardless of slideOnCeiling). Start
+// just in contact (capsule top 2.32 vs ceiling bottom 2.30) so the collide pass
+// reports the plane this frame.
+const ceil = move(2.08, 1.0, 4.0, { slideCeil: 0 });
+check('ceiling detected moving up', ceil && ceil.ceil === 1, `ceil=${ceil?.ceil}`);
+check('ceiling stops the upward velocity', ceil && ceil.vy <= 0.01, `vy=${ceil?.vy.toFixed(3)}`);
+
+// 7) maxSlides = 0 is clamped to at least one slide (never a frozen no-op move).
+const clamped = move(-2.06, 3.2, 0, { maxSlides: 0 });
+check('maxSlides<1 still moves', clamped && clamped.dx > 0.02, `dx=${clamped?.dx.toFixed(4)}`);
+
console.log(pass ? '\nMOVER_SMOKE PASS' : '\nMOVER_SMOKE FAIL');
process.exit(pass ? 0 : 1);
diff --git a/src/esengine/bindings/PhysicsQueries.cpp b/src/esengine/bindings/PhysicsQueries.cpp
index 935ced9f3..02c88158f 100644
--- a/src/esengine/bindings/PhysicsQueries.cpp
+++ b/src/esengine/bindings/PhysicsQueries.cpp
@@ -73,6 +73,28 @@ static bool moverPlaneCallback(b2ShapeId shapeId, const b2PlaneResult* pr, void*
return true;
}
+// Floor-snap down-probe: tracks the closest floor-classified hit (excluding self).
+// Returns 1.0 for every hit so the cast evaluates all shapes; the closest floor is
+// kept manually rather than via cast clipping (a nearer wall must not hide a floor).
+static float g_snapClosest = 1.0f;
+static b2Vec2 g_snapNormal = {0.0f, 0.0f};
+static bool g_snapHit = false;
+static b2Vec2 g_snapUp = {0.0f, 1.0f};
+static float g_snapFloorCos = 0.0f;
+
+static float snapCastCallback(b2ShapeId shapeId, b2Vec2 point, b2Vec2 normal, float fraction, void* context) {
+ (void)point;
+ (void)context;
+ if (entityFromShape(shapeId) == g_moverSelfEntity) return 1.0f;
+ float d = normal.x * g_snapUp.x + normal.y * g_snapUp.y;
+ if (d >= g_snapFloorCos && fraction < g_snapClosest) {
+ g_snapClosest = fraction;
+ g_snapNormal = normal;
+ g_snapHit = true;
+ }
+ return 1.0f;
+}
+
extern "C" {
EMSCRIPTEN_KEEPALIVE
@@ -203,7 +225,8 @@ int physics_overlapAABB(float minX, float minY, float maxX, float maxY, uint32_t
EMSCRIPTEN_KEEPALIVE
int physics_moveCharacter(float px, float py, float c1x, float c1y, float c2x, float c2y, float radius,
float velX, float velY, float dt, float upX, float upY, float floorCos,
- uint32_t maskBits, uint32_t selfEntity) {
+ uint32_t maskBits, uint32_t selfEntity,
+ float skinWidth, int maxSlides, float snapLength, int slideOnCeiling) {
if (!b2World_IsValid(g_ctx.worldId)) return 0;
g_moverSelfEntity = selfEntity;
@@ -214,13 +237,18 @@ int physics_moveCharacter(float px, float py, float c1x, float c1y, float c2x, f
b2QueryFilter filter = b2DefaultQueryFilter();
filter.maskBits = static_cast<uint64_t>(maskBits);
+ // skinWidth keeps the capsule a small margin off surfaces (less jitter, no
+ // visual overlap) — a slightly larger collision radius does exactly that.
+ float moverRadius = radius + (skinWidth > 0.0f ? skinWidth : 0.0f);
+ int slides = maxSlides > 0 ? maxSlides : 1;
+
const float tolerance = 0.001f;
- for (int iteration = 0; iteration < 5; ++iteration) {
+ for (int iteration = 0; iteration < slides; ++iteration) {
g_moverPlaneCount = 0;
b2Capsule mover;
mover.center1 = {pos.x + c1x, pos.y + c1y};
mover.center2 = {pos.x + c2x, pos.y + c2y};
- mover.radius = radius;
+ mover.radius = moverRadius;
b2World_CollideMover(g_ctx.worldId, &mover, filter, moverPlaneCallback, nullptr);
b2PlaneSolverResult result = b2SolvePlanes(b2Sub(target, pos), g_moverPlanes, g_moverPlaneCount);
pos = b2Add(pos, result.translation);
@@ -241,6 +269,38 @@ int physics_moveCharacter(float px, float py, float c1x, float c1y, float c2x, f
else { onWall = true; }
}
+ // slideOnCeiling=false: a ceiling hit cancels the upward velocity instead of
+ // sliding along it, so the character drops straight back down.
+ if (onCeiling && slideOnCeiling == 0) {
+ float vUp = newVel.x * upX + newVel.y * upY;
+ if (vUp > 0.0f) { newVel.x -= vUp * upX; newVel.y -= vUp * upY; }
+ }
+
+ // Floor snap: when not rising and not already grounded, probe down up to
+ // snapLength and stick to a floor within reach, so the character stays glued to
+ // descending stairs/slopes instead of launching off each ledge.
+ if (snapLength > 0.0f && !onFloor) {
+ float vUp = newVel.x * upX + newVel.y * upY;
+ if (vUp <= 0.01f) {
+ g_snapClosest = 1.0f;
+ g_snapHit = false;
+ g_snapUp = up;
+ g_snapFloorCos = floorCos;
+ b2Vec2 pts[2] = { {pos.x + c1x, pos.y + c1y}, {pos.x + c2x, pos.y + c2y} };
+ b2ShapeProxy proxy = b2MakeProxy(pts, 2, moverRadius);
+ b2Vec2 down = {-upX * snapLength, -upY * snapLength};
+ b2World_CastShape(g_ctx.worldId, &proxy, down, filter, snapCastCallback, nullptr);
+ if (g_snapHit) {
+ pos = b2Add(pos, {down.x * g_snapClosest, down.y * g_snapClosest});
+ onFloor = true;
+ fnx = g_snapNormal.x;
+ fny = g_snapNormal.y;
+ float vn = newVel.x * g_snapNormal.x + newVel.y * g_snapNormal.y;
+ if (vn < 0.0f) { newVel.x -= vn * g_snapNormal.x; newVel.y -= vn * g_snapNormal.y; }
+ }
+ }
+ }
+
g_moverBuffer[0] = pos.x - px;
g_moverBuffer[1] = pos.y - py;
g_moverBuffer[2] = newVel.x;