Matter.js Engine.merge Internal State Updates

When combining two physics engines in Matter.js using Matter.Engine.merge(engineA, engineB), the physics engine unifies their configurations, composite hierarchies, and runtime state into the primary engine instance. This article details the exact internal states modified during this merge, covering engine-level configurations, collision caches, and world composite structures.

Engine Configuration and Properties

The operation invokes Matter.Common.extend(engineA, engineB), copying top-level properties and settings from engineB directly onto engineA. The internal properties updated include:

• Solver Iterations: Values for positionIterations, velocityIterations, and constraintIterations are overridden by the values defined in engineB.
• Timing State: Timing configurations, including timing.timeScale, timing.timestamp, and custom delta trackers, adopt the incoming engine's settings.
• Engine Flags and Options: Configuration flags, such as enableSleeping, custom plugins, and user-defined engine parameters, are merged and updated on engineA.

Collision Pairs and Cache Invalidation

To maintain physical consistency and prevent ghost collisions between entities that previously existed in separate coordinate spaces, the internal cache of engineA is reset:

• Active Pairs (engineA.pairs): Engine.clear(engineA) is invoked, clearing the active collision pairs registry. All pre-existing contacts, collision separation trackers, and manifold states are wiped.
• Broadphase Structures: Internal collision broadphase tables and pair caches are cleared to eliminate stale body references before the next update step.
• Metrics and Counters: Any collision metrics or frame-specific debugging counters stored on the engine instance are reset.

World Composite Hierarchy

The physical entities managed by both engines are consolidated inside the destination engine's root world:

• Composite Assignment: If engineB.world exists, engineA.world is updated to incorporate the structure of engineB.world.
• Entities Collection: The collections for bodies, constraints, and nested composites from engineB.world are added into engineA.world via Matter.Composite.add.
• Hierarchy Invalidation: Adding entities marks the composite tree as modified (composite.isModified = true), forcing Matter.js to recompute flattened body lists, constraint indices, and total bounds during the subsequent update cycle.

Broadphase and Detector Re-synchronization

Although Engine.merge modifies the static structure immediately, the collision detector's internal spatial index is updated during the next Matter.Engine.update call:

• Spatial Index Rebuild: Spatial hashing grids or bounding volume hierarchies discard previous spatial cells and repopulate them using the combined body list from the merged world.
• Pair Generation: New collision pairs are formed between bodies originating from engineA and engineB from scratch, ensuring initial overlap resolution and constraint stabilization occur cleanly.