TypeScript: World.restoreSnapshot() leaks ~1730 bytes per call regardless of world size

[jounih]

World.restoreSnapshot() leaks a fixed ~1730 bytes of WASM memory per call, even when the returned world is free()d.

The leak is independent of world size, which suggests a fixed-size allocation per restored World rather than anything proportional to the snapshot contents.

(Filed here rather than rapier.js, which is archived and points to typescript/.)

Environment

• @dimforge/rapier2d-deterministic-compat 0.20.0
• Node v25.4.0, macOS 15 (darwin/arm64)

Reproduction

// node --expose-gc leak-repro.mjs [cycles] [bodies]
import RAPIER from "@dimforge/rapier2d-deterministic-compat";

const CYCLES = Number(process.argv[2] ?? 4000);
const BODIES = Number(process.argv[3] ?? 40);
await RAPIER.init();

function buildWorld() {
  const world = new RAPIER.World(new RAPIER.Vector2(0, -9.81));
  const ground = world.createRigidBody(RAPIER.RigidBodyDesc.fixed().setTranslation(0, -1));
  world.createCollider(RAPIER.ColliderDesc.cuboid(50, 1), ground);
  for (let i = 0; i < BODIES; i++) {
    const b = world.createRigidBody(
      RAPIER.RigidBodyDesc.dynamic().setTranslation((i % 8) * 1.1, 1 + Math.floor(i / 8) * 1.1),
    );
    world.createCollider(RAPIER.ColliderDesc.cuboid(0.5, 0.5).setDensity(1), b);
  }
  for (let i = 0; i < 60; i++) world.step();
  return world;
}

const sample = () => (global.gc(), global.gc(), process.memoryUsage());

const source = buildWorld();
const snapshot = source.takeSnapshot();

// Warm up so one-time allocations are not counted as growth.
for (let i = 0; i < 200; i++) RAPIER.World.restoreSnapshot(snapshot).free();

const before = sample();
for (let i = 0; i < CYCLES; i++) {
  const w = RAPIER.World.restoreSnapshot(snapshot);
  w.step();
  w.free();
}
const after = sample();
console.log(`external: ${((after.external - before.external) / CYCLES).toFixed(1)} B/cycle`);

// Control: step + takeSnapshot on one world, no restore.
const control = buildWorld();
const cBefore = sample();
for (let i = 0; i < CYCLES; i++) { control.step(); control.takeSnapshot(); }
const cAfter = sample();
console.log(`control:  ${((cAfter.external - cBefore.external) / CYCLES).toFixed(1)} B/cycle`);

Results

external is where WASM linear memory shows up in Node's accounting. 2500 cycles each:

bodies	snapshot size	restoreSnapshot + free	control (step + takeSnapshot)
5	7,947 B	1730.2 B/cycle	0.0 B/cycle
40	60,114 B	1730.2 B/cycle	26.2 B/cycle
300	441,562 B	1730.2 B/cycle	180.0 B/cycle

The snapshot size spans 55× while the leaked amount is byte-identical, and the control path — which exercises stepping and serialization but never restores — is essentially flat. Over 4000 cycles at 40 bodies the process also grows ~48 MB RSS and ~240 B/cycle of JS heap.

Why this matters

This shows up in rollback netcode, where restoreSnapshot is called on every correction. At a realistic 1–2 rollbacks/second that is roughly 6–13 MB/hour of unbounded growth — slow, but it never plateaus, so a long session eventually dies. There is no workaround from the JS side: the returned world is freed, and nothing is retained by the caller.

Happy to test a patch or provide more instrumentation if useful.

[Bardakor]

I reproduced this on @dimforge/rapier2d-deterministic-compat@0.20.0 and isolated the fixed-size part to the RawDeserializedWorld lifetime.

RawSerializationPipeline.deserializeAll() returns an owned wasm-bindgen wrapper. World.fromRaw() drains its nine fields with the take*() methods, but never frees the now-empty wrapper. World.free() cannot reach that container afterward.

To separate ownership from garbage-collector timing, I captured the actual WASM memory buffer and disabled finalizer callbacks before package initialization. Reusing one serialization pipeline, I measured 1,730.15, 1,703.94, and 1,703.94 WASM bytes per restore for 5, 40, and 300 bodies. Explicitly freeing the raw container after World.fromRaw() held the buffer at zero growth in all three cases.

There is a second lifetime mismatch in World.restoreSnapshot(): its temporary SerializationPipeline is not explicitly freed, despite the class's manual-free contract. It is not the source of the fixed WASM slope in my isolation, but it should be closed at the same boundary.

I built and tested the patch locally. The production change is two ownership boundaries:

public static fromRaw(raw: RawDeserializedWorld): World {
    if (!raw) return null;

    try {
        return new World(
            VectorOps.fromRaw(raw.takeGravity()),
            raw.takeIntegrationParameters(),
            raw.takeIslandManager(),
            raw.takeBroadPhase(),
            raw.takeNarrowPhase(),
            raw.takeBodies(),
            raw.takeColliders(),
            raw.takeImpulseJoints(),
            raw.takeMultibodyJoints(),
        );
    } finally {
        raw.free();
    }
}

public static restoreSnapshot(data: Uint8Array): World {
    let deser = new SerializationPipeline();
    try {
        return deser.deserializeAll(data);
    } finally {
        deser.free();
    }
}

I used a real WASM-memory regression rather than mocking .free(). The test captures the module's WebAssembly.Memory, disables finalizer callbacks, warms 200 restores, then restores and frees 2,500 empty worlds. On current master, 2D grew from 1,572,864 to 5,898,240 bytes and 3D to 6,291,456 bytes. With the patch, both remain at 1,572,864 bytes. The test covers the deterministic 2D and 3D compat builds, and the full compat suite passes with 5 suites and 8 tests.

[jounih]

Thanks @Bardakor — that matches what I see, and I can confirm the diagnosis independently.

I applied your two changes to the shipped 0.20.0 bundle (patching the minified dist/rapier.mjs in place, so this is the released artifact rather than a build from source) and re-ran the reproducer from the issue. I also ablated the two changes separately, since your note said the SerializationPipeline was not the source of the fixed slope — that turns out to be true, but it is not free either.

B/cycle of external growth, 2500 cycles, same machine as the original report:

patch	5 bodies	40 bodies	300 bodies
none (baseline)	1730.2	1730.2	1730.2
fromRaw free only	0.0	26.2	26.2
restoreSnapshot free only	1704.0	1730.2	1730.2
both	0.0	0.0	0.0

So: raw.free() in World.fromRaw is indeed the whole of the fixed 1730.2 B, exactly as you found. But freeing the temporary SerializationPipeline is not just tidiness — without it a reproducible 26.2 B/cycle residual remains at 40 and 300 bodies (0.0 at 5, so it appears above some small threshold). Only both changes together reach zero. Each figure above was reproducible to the decimal across repeated runs.

I also ran my own determinism suite against the patched build: 231 tests green, including golden state checksums pinned on arm64 and compared bit-for-bit, plus post-restore resimulation. So the patch is behaviour-preserving on the snapshot/restore path, which is the part I would have worried about.

For what it is worth on impact: this is the leak in rollback netcode, where restoreSnapshot runs on every correction. With both changes the growth is not merely reduced, it is gone — the process holds flat instead of climbing without ever plateauing.

Happy to test a PR branch against the same suite if that is useful.

[Bardakor]

Thanks for doing the ablation and running the determinism suite. The 26.2 B/cycle residual makes the SerializationPipeline cleanup clearly part of the fix, rather than only lifecycle hygiene.

I opened draft PR #994 with both finally blocks and the real WebAssembly.Memory regression for the deterministic 2D and 3D compat builds: #994

Running that branch against the same 231-test suite would be useful if you have the time.