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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(physics): character controller honors skinWidth/maxSlides/snapLength/slideOnCeiling
esenginebe3ed49821dd
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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) => numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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) => numberdiff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.mdindex a7aa088c4..2bcf88515 100644--- a/sdk/etc/physics.api.md+++ b/sdk/etc/physics.api.md@@ -292,7 +292,7 @@ getRevoluteMotorTorque: (entity: Entity) => numbergetWheelJointMotorTorque: (entity: Entity) => numberhasMouseJoint: () => booleanisAwake: (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 | nulloverlapAABB: (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) => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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) => numberdiff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.cppindex 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_tEMSCRIPTEN_KEEPALIVEint 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, fb2QueryFilter 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, felse { 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;