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): kinematic bodies carry riders; disabled bodies and re-parented joints behave

esengine461fd5cda819
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d9dba3193..4fa820a85 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -3712,6 +3712,7 @@ uvs: number[] | undefined
## Mesh2DPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
@@ -4077,6 +4078,7 @@ texture: number
## ParticlePlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): ParticlePlugin
static prototype: ParticlePlugin
@@ -4259,6 +4261,7 @@ _physics_raycast: (originX: number, originY: number, dirX: number, dirY: number,
_physics_setAngularVelocity: (entityId: number, omega: number) => void
_physics_setAwake: (entityId: number, awake: number) => void
_physics_setBodyEnabled: (entityId: number, enabled: number) => void
+_physics_setBodyTargetTransform: (entityId: number, x: number, y: number, angle: number, dt: number) => void
_physics_setBodyTransform: (entityId: number, x: number, y: number, angle: number) => void
_physics_setDistanceJointLength: (entityId: number, length: number) => void
_physics_setDistanceJointLimits: (entityId: number, minLength: number, maxLength: number) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9f0dd53e7..1c38b6b4b 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3707,6 +3707,7 @@ uvs: number[] | undefined
## Mesh2DPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
@@ -4072,6 +4073,7 @@ texture: number
## ParticlePlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): ParticlePlugin
static prototype: ParticlePlugin
@@ -4254,6 +4256,7 @@ _physics_raycast: (originX: number, originY: number, dirX: number, dirY: number,
_physics_setAngularVelocity: (entityId: number, omega: number) => void
_physics_setAwake: (entityId: number, awake: number) => void
_physics_setBodyEnabled: (entityId: number, enabled: number) => void
+_physics_setBodyTargetTransform: (entityId: number, x: number, y: number, angle: number, dt: number) => void
_physics_setBodyTransform: (entityId: number, x: number, y: number, angle: number) => void
_physics_setDistanceJointLength: (entityId: number, length: number) => void
_physics_setDistanceJointLimits: (entityId: number, minLength: number, maxLength: number) => void
diff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.md
index a7f190f7c..a7aa088c4 100644
--- a/sdk/etc/physics.api.md
+++ b/sdk/etc/physics.api.md
@@ -469,6 +469,7 @@ _physics_raycast: (originX: number, originY: number, dirX: number, dirY: number,
_physics_setAngularVelocity: (entityId: number, omega: number) => void
_physics_setAwake: (entityId: number, awake: number) => void
_physics_setBodyEnabled: (entityId: number, enabled: number) => void
+_physics_setBodyTargetTransform: (entityId: number, x: number, y: number, angle: number, dt: number) => void
_physics_setBodyTransform: (entityId: number, x: number, y: number, angle: number) => void
_physics_setDistanceJointLength: (entityId: number, length: number) => void
_physics_setDistanceJointLimits: (entityId: number, minLength: number, maxLength: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 5748fe0e0..8a1ea1ce5 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3714,6 +3714,7 @@ uvs: number[] | undefined
## Mesh2DPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
@@ -4079,6 +4080,7 @@ texture: number
## ParticlePlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): ParticlePlugin
static prototype: ParticlePlugin
@@ -4261,6 +4263,7 @@ _physics_raycast: (originX: number, originY: number, dirX: number, dirY: number,
_physics_setAngularVelocity: (entityId: number, omega: number) => void
_physics_setAwake: (entityId: number, awake: number) => void
_physics_setBodyEnabled: (entityId: number, enabled: number) => void
+_physics_setBodyTargetTransform: (entityId: number, x: number, y: number, angle: number, dt: number) => void
_physics_setBodyTransform: (entityId: number, x: number, y: number, angle: number) => void
_physics_setDistanceJointLength: (entityId: number, length: number) => void
_physics_setDistanceJointLimits: (entityId: number, minLength: number, maxLength: number) => void
diff --git a/sdk/src/physics/PhysicsModuleLoader.ts b/sdk/src/physics/PhysicsModuleLoader.ts
index d7e89c994..5e0288516 100644
--- a/sdk/src/physics/PhysicsModuleLoader.ts
+++ b/sdk/src/physics/PhysicsModuleLoader.ts
@@ -49,6 +49,7 @@ export interface PhysicsWasmModule {
_physics_step(dt: number): void;
_physics_setBodyTransform(entityId: number, x: number, y: number, angle: number): void;
+ _physics_setBodyTargetTransform(entityId: number, x: number, y: number, angle: number, dt: number): void;
_physics_getDynamicBodyCount(): number;
_physics_getDynamicBodyTransforms(): number;
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index e28ddad51..f7f670978 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -647,6 +647,24 @@ export function jointChangedOrGone(world: App['world'], entity: Entity, sinceTic
return true; // no joint component left → gone
}
+/**
+ * For a tracked joint entity: whether its connected partner body is no longer
+ * tracked (despawned, or its RigidBody removed). Box2D auto-destroys a joint
+ * when either connected body dies, but the owner keeps its unchanged joint
+ * component and stays in `trackedJoints` — so without re-establishing it here the
+ * joint is silently dead forever, even after the partner respawns.
+ * @internal
+ */
+export function jointPartnerGone(world: App['world'], entity: Entity, trackedEntities: Set<Entity>): boolean {
+ for (const J of JOINT_TYPES) {
+ if (world.has(entity, J)) {
+ const connected = (world.get(entity, J) as { connectedEntity: number }).connectedEntity as Entity;
+ return !trackedEntities.has(connected);
+ }
+ }
+ return false;
+}
+
/**
* Wire the per-frame physics system into the app. Owns tracked-entity
* / tracked-joint / parented sets via the enclosing closure so the
@@ -842,7 +860,8 @@ export function registerPhysicsSystem(
// Destroy joints whose definition changed or whose component was
// removed; createPendingJoints re-adds present+enabled ones.
for (const entity of [...trackedJoints]) {
- if (jointChangedOrGone(world, entity, lastEntitySyncTick)) {
+ if (jointChangedOrGone(world, entity, lastEntitySyncTick)
+ || jointPartnerGone(world, entity, trackedEntities)) {
module._physics_destroyJoint(entity);
trackedJoints.delete(entity);
}
@@ -856,13 +875,17 @@ export function registerPhysicsSystem(
// Kinematic bodies are driven by their Transform (changed via gameplay,
// not tracked as a physics edit) — push every step, even when the
- // reconcile above was skipped.
+ // reconcile above was skipped. Drive them toward the target over the
+ // fixed step so Box2D derives their velocity from the delta: that
+ // velocity is what carries/pushes resting dynamic bodies (a plain
+ // teleport reports zero velocity, so platforms wouldn't move riders).
for (const entity of kinematicEntities) {
const wt = world.get(entity, Transform) as TransformData;
- module._physics_setBodyTransform(
+ module._physics_setBodyTargetTransform(
entity,
wt.worldPosition.x * invPpu, wt.worldPosition.y * invPpu,
quatToAngleZ(wt.worldRotation),
+ fixedDt,
);
}
diff --git a/sdk/tests/physicsReconcile.test.ts b/sdk/tests/physicsReconcile.test.ts
index 825a8fab5..7a2e83577 100644
--- a/sdk/tests/physicsReconcile.test.ts
+++ b/sdk/tests/physicsReconcile.test.ts
@@ -12,7 +12,7 @@ import { createMockModule } from './mocks/wasm';
import {
BoxCollider, CircleCollider, CapsuleCollider, RevoluteJoint,
} from '../src/physics/PhysicsComponents';
-import { colliderSignature, jointChangedOrGone } from '../src/physics/PhysicsSystem';
+import { colliderSignature, jointChangedOrGone, jointPartnerGone } from '../src/physics/PhysicsSystem';
function testWorld(): World {
const mod = createMockModule();
@@ -64,3 +64,29 @@ describe('jointChangedOrGone', () => {
expect(jointChangedOrGone(world, e, world.getWorldTick())).toBe(false);
});
});
+
+describe('jointPartnerGone', () => {
+ it('is false while the connected partner is still tracked', () => {
+ const world = testWorld();
+ const owner = world.spawn();
+ const partner = world.spawn();
+ world.insert(owner, RevoluteJoint, { connectedEntity: partner } as never);
+ expect(jointPartnerGone(world, owner, new Set([owner, partner]))).toBe(false);
+ });
+
+ it('is true once the connected partner drops out of the tracked set (despawn)', () => {
+ const world = testWorld();
+ const owner = world.spawn();
+ const partner = world.spawn();
+ world.insert(owner, RevoluteJoint, { connectedEntity: partner } as never);
+ // Partner despawned → no longer tracked; the joint (auto-destroyed by
+ // Box2D) must be re-established, not left silently dead forever.
+ expect(jointPartnerGone(world, owner, new Set([owner]))).toBe(true);
+ });
+
+ it('is false when there is no joint component (that is jointChangedOrGone\'s job)', () => {
+ const world = testWorld();
+ const e = world.spawn();
+ expect(jointPartnerGone(world, e, new Set([e]))).toBe(false);
+ });
+});
diff --git a/src/esengine/bindings/PhysicsModuleEntry.cpp b/src/esengine/bindings/PhysicsModuleEntry.cpp
index fe37a47e4..682c42e80 100644
--- a/src/esengine/bindings/PhysicsModuleEntry.cpp
+++ b/src/esengine/bindings/PhysicsModuleEntry.cpp
@@ -218,6 +218,20 @@ void physics_setBodyTransform(uint32_t entityId, float x, float y, float angle)
b2Body_SetTransform(it->second, {x, y}, b2MakeRot(angle));
}
+// Drive a kinematic body toward a target pose over `dt`, deriving its
+// linear+angular velocity from the delta (unlike setBodyTransform, which
+// teleports with zero velocity). The velocity is what the contact solver uses
+// to carry/push resting dynamic bodies — a moving platform is dead without it.
+EMSCRIPTEN_KEEPALIVE
+void physics_setBodyTargetTransform(uint32_t entityId, float x, float y, float angle, float dt) {
+ auto it = g_ctx.entityToBody.find(entityId);
+ if (it == g_ctx.entityToBody.end()) return;
+ if (!b2Body_IsValid(it->second)) return;
+
+ b2Transform target = { {x, y}, b2MakeRot(angle) };
+ b2Body_SetTargetTransform(it->second, target, dt, true);
+}
+
EMSCRIPTEN_KEEPALIVE
int physics_getDynamicBodyCount() {
return static_cast<int>(g_ctx.dynamicBodyEntities.size());
@@ -230,6 +244,10 @@ uintptr_t physics_getDynamicBodyTransforms() {
for (uint32_t entityId : g_ctx.dynamicBodyEntities) {
auto it = g_ctx.entityToBody.find(entityId);
if (it == g_ctx.entityToBody.end() || !b2Body_IsValid(it->second)) continue;
+ // A disabled body is frozen; skip it so the readback doesn't stamp its
+ // stale pose back over a Transform the game is hand-animating while
+ // physics is off (RigidBody.enabled = false).
+ if (!b2Body_IsEnabled(it->second)) continue;
b2Vec2 pos = b2Body_GetPosition(it->second);
float angle = b2Rot_GetAngle(b2Body_GetRotation(it->second));