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.

feat(physics): kinematic move-and-slide CharacterController (2D-parity A1)

esengine85f4fdd84e92
diff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.ts
new file mode 100644
index 000000000..99acb3fea
--- /dev/null
+++ b/sdk/src/physics/CharacterController.ts
@@ -0,0 +1,347 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file CharacterController.ts
+ * @brief Kinematic move-and-slide character controller (Godot CharacterBody2D
+ * semantics) built on the existing Box2D shape-cast queries.
+ *
+ * The controller is gameplay logic, so it lives entirely in the SDK and never
+ * touches C++: it reads the entity's own collider for the cast shape, sweeps it
+ * through the world with `Physics.shapeCast*`, and resolves collisions by sliding
+ * along surfaces. It writes the resolved pose to `Transform`; if the entity also
+ * carries a Kinematic `RigidBody`, `PhysicsStepSystem` then pushes that Transform
+ * into Box2D so dynamic bodies see the character. Movement itself is query-driven,
+ * so a body is recommended (for others to collide with) but not required.
+ *
+ * Units: `velocity`/positions are world pixels (matching `Transform`); collider
+ * dimensions are meters and are scaled to pixels via `Physics.getPixelsPerUnit()`.
+ */
+import type { App } from '../app';
+import type { Entity, Vec2 } from '../types';
+import { defineComponent, Transform, type TransformData } from '../component';
+import { Schedule, defineSystem, GetWorld } from '../system';
+import { Query, Mut } from '../query';
+import { Res, Time, type TimeData } from '../resource';
+import { playModeOnly } from '../env';
+import { PhysicsAPI, type Physics } from './Physics';
+import { BoxCollider, CircleCollider, CapsuleCollider } from './PhysicsComponents';
+import type {
+ BoxColliderData, CircleColliderData, CapsuleColliderData,
+} from './PhysicsComponents';
+import type { World } from '../world';
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export interface CharacterControllerData {
+ /** Desired velocity in world pixels/second; set it from gameplay each step. */
+ velocity: Vec2;
+ /** Up direction for floor/ceiling classification (opposes gravity). */
+ up: Vec2;
+ /** Max walkable slope, measured from `up` (radians). Steeper = wall. */
+ floorMaxAngle: number;
+ /** Slide iterations per move (corners need more than one). */
+ maxSlides: number;
+ /** Gap kept from surfaces (pixels) so the body doesn't stick/jitter. */
+ skinWidth: number;
+ /** Down-probe length (pixels) to stay glued to floors on slopes/stairs; 0 = off. */
+ snapLength: number;
+ /** When false, a ceiling hit stops the remaining move instead of sliding along it. */
+ slideOnCeiling: boolean;
+ /** Collision layers that block the character. */
+ maskBits: number;
+
+ /** Output: touched a surface classified as floor this move. */
+ isOnFloor: boolean;
+ /** Output: touched a surface classified as wall this move. */
+ isOnWall: boolean;
+ /** Output: touched a surface classified as ceiling this move. */
+ isOnCeiling: boolean;
+ /** Output: normal of the last floor touched (zero when airborne). */
+ floorNormal: Vec2;
+ /** Output: actual displacement / dt after collisions (pixels/second). */
+ realVelocity: Vec2;
+}
+
+export const CharacterController = defineComponent<CharacterControllerData>('CharacterController', {
+ velocity: { x: 0, y: 0 },
+ up: { x: 0, y: 1 },
+ floorMaxAngle: 0.785398, // 45°
+ maxSlides: 4,
+ skinWidth: 1,
+ snapLength: 0,
+ slideOnCeiling: true,
+ maskBits: 0xFFFF,
+ isOnFloor: false,
+ isOnWall: false,
+ isOnCeiling: false,
+ floorNormal: { x: 0, y: 0 },
+ realVelocity: { x: 0, y: 0 },
+}, {
+ fields: {
+ floorMaxAngle: { min: 0, max: 1.5708, step: 0.01, unit: 'rad', tooltip: 'Max walkable slope from up (radians)' },
+ maxSlides: { min: 1, max: 8, step: 1, advanced: true },
+ skinWidth: { min: 0, step: 0.25, unit: 'px', advanced: true },
+ snapLength: { min: 0, step: 0.5, unit: 'px', tooltip: 'Floor-snap probe length; 0 disables stair/slope stick' },
+ slideOnCeiling: { advanced: true },
+ up: { advanced: true },
+ maskBits: { bitmask: { bits: 16, source: 'collisionLayers' }, advanced: true },
+ isOnFloor: { advanced: true },
+ isOnWall: { advanced: true },
+ isOnCeiling: { advanced: true },
+ floorNormal: { advanced: true },
+ realVelocity: { advanced: true },
+ },
+});
+
+// =============================================================================
+// move-and-slide core (pure — injectable cast, no wasm/world dependency)
+// =============================================================================
+
+/** Nearest blocking hit along a sweep: surface `n*` and the `[0,1]` sweep fraction. */
+export interface SlideHit {
+ nx: number;
+ ny: number;
+ fraction: number;
+}
+
+/**
+ * Sweep the character shape from `(ox,oy)` by `(dx,dy)` (pixels) and return the
+ * nearest hit that blocks it, or `null` for a clear path. Self-collision and the
+ * mask filter are the caller's responsibility.
+ */
+export type SlideCast = (ox: number, oy: number, dx: number, dy: number) => SlideHit | null;
+
+export interface MoveAndSlideParams {
+ startX: number;
+ startY: number;
+ motionX: number;
+ motionY: number;
+ velX: number;
+ velY: number;
+ upX: number;
+ upY: number;
+ floorMaxAngle: number;
+ maxSlides: number;
+ skinWidth: number;
+ snapLength: number;
+ slideOnCeiling: boolean;
+ wasOnFloor: boolean;
+}
+
+export interface MoveAndSlideResult {
+ x: number;
+ y: number;
+ velX: number;
+ velY: number;
+ isOnFloor: boolean;
+ isOnWall: boolean;
+ isOnCeiling: boolean;
+ floorNormalX: number;
+ floorNormalY: number;
+}
+
+const EPS = 1e-6;
+
+/**
+ * Resolve one move: advance toward the first contact, classify the surface, then
+ * project the leftover motion (and velocity) onto it and repeat. Velocity is slid
+ * by the same projections so a grounded body's downward gravity doesn't accumulate
+ * — the contract matches Godot's `move_and_slide`.
+ */
+export function moveAndSlide(p: MoveAndSlideParams, cast: SlideCast): MoveAndSlideResult {
+ let x = p.startX, y = p.startY;
+ let mx = p.motionX, my = p.motionY;
+ let vx = p.velX, vy = p.velY;
+ let onFloor = false, onWall = false, onCeiling = false;
+ let fnX = 0, fnY = 0;
+
+ const ulen = Math.hypot(p.upX, p.upY) || 1;
+ const ux = p.upX / ulen, uy = p.upY / ulen;
+ const cosFloor = Math.cos(p.floorMaxAngle);
+
+ for (let i = 0; i < p.maxSlides; i++) {
+ const len = Math.hypot(mx, my);
+ if (len < EPS) break;
+
+ const hit = cast(x, y, mx, my);
+ if (!hit) { x += mx; y += my; break; }
+
+ const frac = hit.fraction < 0 ? 0 : hit.fraction > 1 ? 1 : hit.fraction;
+ const travel = Math.max(0, frac * len - p.skinWidth);
+ x += (mx / len) * travel;
+ y += (my / len) * travel;
+
+ const nl = Math.hypot(hit.nx, hit.ny) || 1;
+ const nx = hit.nx / nl, ny = hit.ny / nl;
+ const nDotUp = nx * ux + ny * uy;
+ if (nDotUp >= cosFloor) { onFloor = true; fnX = nx; fnY = ny; }
+ else if (nDotUp <= -cosFloor) onCeiling = true;
+ else onWall = true;
+
+ const leftoverX = mx * (1 - frac);
+ const leftoverY = my * (1 - frac);
+ const dotM = leftoverX * nx + leftoverY * ny;
+ mx = leftoverX - nx * dotM;
+ my = leftoverY - ny * dotM;
+
+ const dotV = vx * nx + vy * ny;
+ vx -= nx * dotV;
+ vy -= ny * dotV;
+
+ if (onCeiling && !p.slideOnCeiling) break;
+ }
+
+ // Floor snap: keep a grounded body glued to descending ground (stairs/slopes)
+ // so it doesn't launch off ledges. Skip while moving up (a jump must leave).
+ if (p.snapLength > 0 && p.wasOnFloor && !onFloor) {
+ const velUp = vx * ux + vy * uy;
+ if (velUp <= EPS) {
+ const sx = -ux * p.snapLength, sy = -uy * p.snapLength;
+ const hit = cast(x, y, sx, sy);
+ if (hit) {
+ const nl = Math.hypot(hit.nx, hit.ny) || 1;
+ const nx = hit.nx / nl, ny = hit.ny / nl;
+ if (nx * ux + ny * uy >= cosFloor) {
+ const slen = Math.hypot(sx, sy);
+ const frac = hit.fraction < 0 ? 0 : hit.fraction > 1 ? 1 : hit.fraction;
+ const travel = Math.max(0, frac * slen - p.skinWidth);
+ x += (sx / slen) * travel;
+ y += (sy / slen) * travel;
+ onFloor = true; fnX = nx; fnY = ny;
+ }
+ }
+ }
+ }
+
+ return {
+ x, y, velX: vx, velY: vy,
+ isOnFloor: onFloor, isOnWall: onWall, isOnCeiling: onCeiling,
+ floorNormalX: fnX, floorNormalY: fnY,
+ };
+}
+
+// =============================================================================
+// System
+// =============================================================================
+
+/** The character's cast shape, in pixels, resolved from its collider. */
+type CastShape =
+ | { kind: 'box'; hx: number; hy: number; ox: number; oy: number }
+ | { kind: 'circle'; r: number; ox: number; oy: number }
+ | { kind: 'capsule'; r: number; halfH: number; ox: number; oy: number };
+
+/** Read the entity's collider into a pixel-space cast shape, or null if it has none. */
+function resolveCastShape(world: World, entity: Entity, ppu: number): CastShape | null {
+ if (world.has(entity, BoxCollider)) {
+ const c = world.get(entity, BoxCollider) as BoxColliderData;
+ return { kind: 'box', hx: c.halfExtents.x * ppu, hy: c.halfExtents.y * ppu, ox: c.offset.x * ppu, oy: c.offset.y * ppu };
+ }
+ if (world.has(entity, CircleCollider)) {
+ const c = world.get(entity, CircleCollider) as CircleColliderData;
+ return { kind: 'circle', r: c.radius * ppu, ox: c.offset.x * ppu, oy: c.offset.y * ppu };
+ }
+ if (world.has(entity, CapsuleCollider)) {
+ const c = world.get(entity, CapsuleCollider) as CapsuleColliderData;
+ return { kind: 'capsule', r: c.radius * ppu, halfH: c.halfHeight * ppu, ox: c.offset.x * ppu, oy: c.offset.y * ppu };
+ }
+ return null;
+}
+
+/**
+ * Build the nearest-blocking-hit cast for one character: sweep its shape, drop the
+ * character's own body, and keep the lowest-fraction hit.
+ */
+function makeCast(physics: Physics, self: Entity, shape: CastShape, maskBits: number): SlideCast {
+ const t: Vec2 = { x: 0, y: 0 };
+ const c: Vec2 = { x: 0, y: 0 };
+ return (ox, oy, dx, dy) => {
+ c.x = ox + shape.ox; c.y = oy + shape.oy;
+ t.x = dx; t.y = dy;
+ let hits;
+ if (shape.kind === 'box') hits = physics.shapeCastBox(c, { x: shape.hx, y: shape.hy }, 0, t, maskBits);
+ else if (shape.kind === 'circle') hits = physics.shapeCastCircle(c, shape.r, t, maskBits);
+ else hits = physics.shapeCastCapsule({ x: c.x, y: c.y + shape.halfH }, { x: c.x, y: c.y - shape.halfH }, shape.r, t, maskBits);
+
+ let best: SlideHit | null = null;
+ for (const h of hits) {
+ if (h.entity === self) continue;
+ if (best === null || h.fraction < best.fraction) best = { nx: h.normal.x, ny: h.normal.y, fraction: h.fraction };
+ }
+ return best;
+ };
+}
+
+/**
+ * Register the move-and-slide system. Runs in FixedUpdate ahead of the physics
+ * step so the resolved Transform is what gets pushed into a kinematic body.
+ */
+export function registerCharacterControllerSystem(app: App): void {
+ app.addSystemToSchedule(
+ Schedule.FixedUpdate,
+ defineSystem(
+ [Query(Mut(CharacterController)), Res(Time), Res(PhysicsAPI), GetWorld()],
+ (
+ query: Iterable<[Entity, CharacterControllerData]>,
+ time: TimeData,
+ physics: Physics,
+ world: World,
+ ) => {
+ const dt = time.fixedDelta;
+ if (dt <= 0) return;
+ const ppu = physics.getPixelsPerUnit();
+ const invDt = 1 / dt;
+
+ for (const [entity, cc] of query) {
+ const shape = resolveCastShape(world, entity, ppu);
+ if (!shape) continue;
+
+ // Transform is C++-backed: get() yields a converted copy, so the
+ // resolved pose must be written back with set() (mutating the copy
+ // alone would not persist).
+ const transform = world.get(entity, Transform) as TransformData;
+ const startX = transform.position.x;
+ const startY = transform.position.y;
+ const cast = makeCast(physics, entity, shape, cc.maskBits);
+
+ const r = moveAndSlide({
+ startX, startY,
+ motionX: cc.velocity.x * dt,
+ motionY: cc.velocity.y * dt,
+ velX: cc.velocity.x,
+ velY: cc.velocity.y,
+ upX: cc.up.x, upY: cc.up.y,
+ floorMaxAngle: cc.floorMaxAngle,
+ maxSlides: cc.maxSlides,
+ skinWidth: cc.skinWidth,
+ snapLength: cc.snapLength,
+ slideOnCeiling: cc.slideOnCeiling,
+ wasOnFloor: cc.isOnFloor,
+ }, cast);
+
+ // Write both local and world position: PhysicsStepSystem runs next
+ // in this same FixedUpdate and pushes worldPosition into a kinematic
+ // body, before TransformSystem re-derives world from local.
+ transform.position.x = r.x;
+ transform.position.y = r.y;
+ transform.worldPosition.x = r.x;
+ transform.worldPosition.y = r.y;
+ world.set(entity, Transform, transform);
+
+ cc.velocity.x = r.velX;
+ cc.velocity.y = r.velY;
+ cc.isOnFloor = r.isOnFloor;
+ cc.isOnWall = r.isOnWall;
+ cc.isOnCeiling = r.isOnCeiling;
+ cc.floorNormal.x = r.floorNormalX;
+ cc.floorNormal.y = r.floorNormalY;
+ cc.realVelocity.x = (r.x - startX) * invDt;
+ cc.realVelocity.y = (r.y - startY) * invDt;
+ }
+ },
+ { name: 'CharacterControllerSystem', runBefore: ['PhysicsStepSystem'] },
+ ),
+ { runIf: playModeOnly },
+ );
+}
diff --git a/sdk/src/physics/Physics.ts b/sdk/src/physics/Physics.ts
index 492fd74cf..c9d5607db 100644
--- a/sdk/src/physics/Physics.ts
+++ b/sdk/src/physics/Physics.ts
@@ -38,6 +38,15 @@ export class Physics {
if (ppu > 0) this.ppu_ = ppu;
}
+ /**
+ * Live pixels-per-unit (world pixels per Box2D meter). Collider dimensions are
+ * stored in meters, so consumers that cast a collider's shape through the
+ * pixel-space query API (raycast/shapeCast) must scale by this.
+ */
+ getPixelsPerUnit(): number {
+ return this.ppu_;
+ }
+
constructor(app: App) {
const module = app.hasResource(PhysicsRuntime)
? app.getResource(PhysicsRuntime).module
diff --git a/sdk/src/physics/PhysicsPlugin.ts b/sdk/src/physics/PhysicsPlugin.ts
index 7db6a21aa..1151351b2 100644
--- a/sdk/src/physics/PhysicsPlugin.ts
+++ b/sdk/src/physics/PhysicsPlugin.ts
@@ -22,6 +22,7 @@ import { PhysicsBridge } from './PhysicsBridge';
import { PhysicsRuntime } from './PhysicsRuntime';
import { Physics, PhysicsAPI } from './Physics';
import { registerPhysicsSystem } from './PhysicsSystem';
+import { registerCharacterControllerSystem } from './CharacterController';
import {
PhysicsEvents,
type PhysicsPluginConfig,
@@ -135,6 +136,7 @@ export class PhysicsPlugin implements Plugin {
app.getResource(PhysicsRuntime).module = module;
app.insertResource(PhysicsAPI, Physics._fromModule(module));
+ registerCharacterControllerSystem(app);
setupPhysicsDebugDraw(app, PhysicsAPI, PhysicsEvents);
app.setFixedTimestep(this.config_.fixedTimestep);
// Module loaded, world initialized, systems registered.
diff --git a/sdk/src/physics/index.ts b/sdk/src/physics/index.ts
index a302cff29..f5263866b 100644
--- a/sdk/src/physics/index.ts
+++ b/sdk/src/physics/index.ts
@@ -66,3 +66,14 @@ export {
drawPhysicsDebug,
type PhysicsDebugDrawConfig,
} from './PhysicsDebugDraw';
+
+export {
+ CharacterController,
+ moveAndSlide,
+ registerCharacterControllerSystem,
+ type CharacterControllerData,
+ type MoveAndSlideParams,
+ type MoveAndSlideResult,
+ type SlideCast,
+ type SlideHit,
+} from './CharacterController';
diff --git a/sdk/tests/character-controller.test.ts b/sdk/tests/character-controller.test.ts
new file mode 100644
index 000000000..5e5fc60ca
--- /dev/null
+++ b/sdk/tests/character-controller.test.ts
@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { moveAndSlide, type SlideCast, type MoveAndSlideParams } from '../src/physics/CharacterController';
+
+const close = (a: number, b: number, eps = 1e-6) => expect(Math.abs(a - b)).toBeLessThanOrEqual(eps);
+
+/**
+ * A solid half-space for the move-and-slide tests: surface through `point` with
+ * unit normal `n` (pointing toward the moving body). Reports the sweep hit only
+ * when the body moves into the surface.
+ */
+function planeCast(n: { x: number; y: number }, point: { x: number; y: number }): SlideCast {
+ const d = n.x * point.x + n.y * point.y;
+ return (ox, oy, dx, dy) => {
+ const nDotD = n.x * dx + n.y * dy;
+ if (nDotD >= 0) return null;
+ const f = (d - (n.x * ox + n.y * oy)) / nDotD;
+ if (f < 0 || f > 1) return null;
+ return { nx: n.x, ny: n.y, fraction: f };
+ };
+}
+
+const NEVER: SlideCast = () => null;
+
+function params(over: Partial<MoveAndSlideParams>): MoveAndSlideParams {
+ return {
+ startX: 0, startY: 0, motionX: 0, motionY: 0, velX: 0, velY: 0,
+ upX: 0, upY: 1, floorMaxAngle: Math.PI / 4, maxSlides: 4,
+ skinWidth: 0, snapLength: 0, slideOnCeiling: true, wasOnFloor: false,
+ ...over,
+ };
+}
+
+describe('moveAndSlide', () => {
+ it('moves the full motion on a clear path', () => {
+ const r = moveAndSlide(params({ motionX: 7, motionY: -3, velX: 70, velY: -30 }), NEVER);
+ close(r.x, 7); close(r.y, -3);
+ expect(r.isOnFloor || r.isOnWall || r.isOnCeiling).toBe(false);
+ close(r.velX, 70); close(r.velY, -30);
+ });
+
+ it('lands on a floor: stops at the surface, zeroes vertical velocity', () => {
+ const r = moveAndSlide(
+ params({ startY: 5, motionY: -10, velY: -100 }),
+ planeCast({ x: 0, y: 1 }, { x: 0, y: 0 }),
+ );
+ close(r.y, 0);
+ expect(r.isOnFloor).toBe(true);
+ close(r.velY, 0);
+ close(r.floorNormalY, 1);
+ });
+
+ it('preserves horizontal motion while landing (slide along floor)', () => {
+ const r = moveAndSlide(
+ params({ startX: 0, startY: 5, motionX: 5, motionY: -10, velX: 50, velY: -100 }),
+ planeCast({ x: 0, y: 1 }, { x: 0, y: 0 }),
+ );
+ close(r.x, 5); close(r.y, 0);
+ expect(r.isOnFloor).toBe(true);
+ close(r.velX, 50); close(r.velY, 0);
+ });
+
+ it('stops at a wall and zeroes horizontal velocity', () => {
+ const r = moveAndSlide(
+ params({ motionX: 10, velX: 100 }),
+ planeCast({ x: -1, y: 0 }, { x: 10, y: 0 }),
+ );
+ close(r.x, 10);
+ expect(r.isOnWall).toBe(true);
+ close(r.velX, 0);
+ expect(r.isOnFloor).toBe(false);
+ });
+
+ it('classifies an overhang as ceiling', () => {
+ const r = moveAndSlide(
+ params({ motionY: 10, velY: 100 }),
+ planeCast({ x: 0, y: -1 }, { x: 0, y: 10 }),
+ );
+ close(r.y, 10);
+ expect(r.isOnCeiling).toBe(true);
+ });
+
+ it('keeps a skin-width gap from the surface', () => {
+ const r = moveAndSlide(
+ params({ startY: 5, motionY: -10, velY: -100, skinWidth: 1 }),
+ planeCast({ x: 0, y: 1 }, { x: 0, y: 0 }),
+ );
+ close(r.y, 1); // stops 1px short of the floor at y=0
+ expect(r.isOnFloor).toBe(true);
+ });
+
+ it('treats a slope steeper than floorMaxAngle as a wall', () => {
+ // Normal 60° from up → walkable only if floorMaxAngle ≥ 60°; default is 45°.
+ const n = { x: Math.sin(Math.PI / 3), y: Math.cos(Math.PI / 3) }; // (0.866, 0.5)
+ const r = moveAndSlide(
+ params({ startX: 0, startY: 5, motionX: 0, motionY: -10, velY: -100 }),
+ planeCast(n, { x: 0, y: 0 }),
+ );
+ expect(r.isOnWall).toBe(true);
+ expect(r.isOnFloor).toBe(false);
+ });
+
+ it('walks a shallow slope as floor', () => {
+ // Normal 30° from up → walkable under the 45° default.
+ const n = { x: Math.sin(Math.PI / 6), y: Math.cos(Math.PI / 6) }; // (0.5, 0.866)
+ const r = moveAndSlide(
+ params({ startX: 0, startY: 5, motionY: -10, velY: -100 }),
+ planeCast(n, { x: 0, y: 0 }),
+ );
+ expect(r.isOnFloor).toBe(true);
+ });
+
+ it('snaps to a floor below when descending (stair/slope stick)', () => {
+ // Flat horizontal move that ends in the air; a floor sits 2px below.
+ const cast: SlideCast = (ox, oy, dx, dy) => {
+ if (dy >= 0) return null; // only the downward snap probe sees the floor
+ const f = (0 - oy) / dy; // floor plane at y=0, normal up
+ if (f < 0 || f > 1) return null;
+ return { nx: 0, ny: 1, fraction: f };
+ };
+ const r = moveAndSlide(
+ params({ startX: 0, startY: 2, motionX: 5, velX: 50, snapLength: 3, wasOnFloor: true }),
+ cast,
+ );
+ close(r.x, 5);
+ close(r.y, 0);
+ expect(r.isOnFloor).toBe(true);
+ });
+
+ it('does not snap while moving up (a jump must leave the floor)', () => {
+ const cast: SlideCast = (ox, oy, dx, dy) => {
+ if (dy >= 0) return null;
+ const f = (0 - oy) / dy;
+ if (f < 0 || f > 1) return null;
+ return { nx: 0, ny: 1, fraction: f };
+ };
+ const r = moveAndSlide(
+ params({ startX: 0, startY: 2, motionY: 4, velY: 40, snapLength: 3, wasOnFloor: true }),
+ cast,
+ );
+ close(r.y, 6); // moved up, no snap
+ expect(r.isOnFloor).toBe(false);
+ });
+
+ it('stops the move at a ceiling when slideOnCeiling is false', () => {
+ // Up-and-right motion into a ceiling; with sliding off, the leftover is dropped.
+ const r = moveAndSlide(
+ params({ motionX: 10, motionY: 10, velX: 100, velY: 100, slideOnCeiling: false }),
+ planeCast({ x: 0, y: -1 }, { x: 0, y: 5 }),
+ );
+ expect(r.isOnCeiling).toBe(true);
+ close(r.y, 5);
+ // leftover horizontal slide is suppressed → x stays at the contact point
+ close(r.x, 5);
+ });
+});