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
feat(physics): kinematic move-and-slide CharacterController (2D-parity A1)
esengine85f4fdd84e92
diff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.tsnew file mode 100644index 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.tsindex 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).modulediff --git a/sdk/src/physics/PhysicsPlugin.ts b/sdk/src/physics/PhysicsPlugin.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});