Changelog

All notable changes to this project are recorded here. The format follows Keep a Changelog and the project uses Semantic Versioning. From 1.0.0, a minor release only adds to the API, a patch release only fixes, and there is no 2.0.0. A release that changes results is a minor release, and its entry says what changes. A snapshot or journal tape is read within the minor version that wrote it and refused across minor versions.

1.3.1 (2026-11-05)

This release makes the compiler check that the library never drops the result of one of its own internal bool functions by mistake. Nothing a program sees changes: no golden line moves, and the snapshot and journal formats keep their versions.

Fixed

• Every internal function that returns bool carries M2_NODISCARD (#342). 231 of them lacked it, so a call that dropped such a result could go on past a refusal, or with an out value left unset, and no compiler warned. With the mark, GCC 14 found 25 calls that drop a result. Each one is meant to, so each now says so with (void):
• 19 setters, whose parameter channel has already counted the misuse;
• 5 second writes of a pair, which cannot fail once the first has passed;
• 1 corner contact step in the polygon manifold, whose result nothing reads.

tools/check_nodiscard.py keeps every new internal bool function marked.

1.3.0 (2026-11-05)

This release adds four calls and settings from the 1.0 API review: a motor joint's budgets change at run time, a water volume's game data changes after creation, a chain's material reads back, and each body has its own sleep threshold. It also makes M2_NODISCARD warn under GCC 14's C23. Every golden line moves, but only by value: no result moves. M2_SNAPSHOT_VERSION goes from 8 to 9 and M2_JOURNAL_VERSION from 9 to 10. As in every minor release, snapshots and tapes written by 1.2 are refused with m2_errorVersion.

Changed

• Results: every golden line moves, by value only, the same in the scalar and AVX2 builds (#336, #338). No result moves.
• The 11 world hash lines move because the world hash now covers each body's sleep threshold. Built with that array left out of the hash, they print 1.2.2's values.
• ROLLBACK_SNAPSHOT hashes a snapshot's bytes, which gain the chain material arrays and the sleep thresholds. JOURNAL_TAPE hashes a tape's bytes, which carry the new journal version, the thresholds in the body create records and an embedded snapshot.

• Formats: M2_SNAPSHOT_VERSION goes from 8 to 9 (#336): the snapshot gains each chain's friction and restitution, and each body's sleep threshold (#338). M2_JOURNAL_VERSION goes from 9 to 10 (#338): the body create record now holds the def's sleep threshold, in bytes that were zero. The record stays 88 bytes. The new records of #329 and #332 leave the journal version as it is, since the reader checks the tape's M2_ABI_VERSION before any record.

Added

• A body's sleep threshold (#338). m2BodyDef.sleepThreshold sets the speed below which a body counts as resting, 0 for the default 0.05 m/s, and m2Body_SetSleepThreshold changes it later. The spin limit scales with it: 0.12 rad/s times the threshold over 0.05. m2Body_GetSleepThreshold reads it back. A body at the default sleeps on the same bits as before. The def stays 80 bytes: the field takes what was its trailing padding.
• m2Chain_GetFriction and m2Chain_GetRestitution (#336). A chain keeps its own material, as its def or m2Chain_SetFriction and m2Chain_SetRestitution last set it, not any link's: m2Shape_SetFriction on one link does not change it. A restore checks it with the ranges the def and the setters use.
• m2MotorJoint_SetMaxForce, m2MotorJoint_SetMaxTorque and m2MotorJoint_GetMaxTorque (#329). A motor joint's budgets change at run time, so a platform can let go of its rider or grip harder without being made again. Each setter takes 0 to M2_FORCE_LIMIT, wakes both bodies, and counts one misuse on another joint type.
• m2WaterVolume_SetUserData (#332). A water volume's game data changes after creation, so the volume keeps its id.

Fixed

• M2_NODISCARD is the attribute under GCC 14's C23 too (#334). In C it waited for __STDC_VERSION__ 202311L, but GCC 14 reports 202000L in its C23 mode. So under GCC the macro was empty, and a program could drop any status from the library without a warning. It now takes the attribute in any dialect after C17 whose compiler has it.

1.2.2 (2026-11-04)

This release makes a body whose rotation is locked hold still whatever spin the host gives it, and makes m2World_Restore refuse three more kinds of state that the step would act on wrongly. No golden line moves, and the snapshot and journal formats keep their versions. One kind of snapshot written by 1.2.0 is now refused: see the frozen pairs below.

Changed

• Results: no golden line moves (#327). Only a body whose rotation is locked, and which m2Body_SetAngularVelocity gives a spin, moves differently: it no longer turns.
• m2World_Restore refuses one kind of snapshot that 1.2.0 wrote (#320): one taken after a static shape was moved into a sleeping body it already paired with, and the world stepped since. 1.2.0 and 1.2.1 restored it and kept the stale contact. 1.2.2 refuses it with m2_errorFormat.

Fixed

• A body whose rotation is locked holds still (#327). m2MotionLocks promises that a locked axis's velocity is zeroed each substep, but the solver zeroed only the linear axes. A locked body given a spin with m2Body_SetAngularVelocity turned at it, and nothing slowed it down: a dynamic box and a kinematic one, each given 3 rad/s, had turned 3 rad after 60 steps. The step now zeroes a locked rotation's angular velocity as it does a locked linear axis's, so it reads 0 after the step. m2Body_SetAngularVelocity still stores the spin between steps.
• m2World_Restore holds each frozen pair to the manifold its shapes give (#320). The step copies forward the manifold of a pair whose shapes are unmoved and whose bodies are each static or asleep for two step ends, and the touching flag decides which bodies a host call wakes. So a snapshot could say that two resting bodies do not touch. Two boxes slept in a stack, and the snapshot gave their pair 0 points: when the host teleported the lower box away, the upper one stayed asleep in the air at y 1.9991 instead of falling to y 0.9999. A restore now refuses a touching flag that disagrees with its manifold's point count, and a frozen pair whose manifold is not the one its shapes give at their bodies' poses. Only its impulses and its persisted bit may differ.
• m2World_Restore refuses a still body that moves (#323): a static body with a velocity, a sleeping body with a velocity, and a non-dynamic body marked asleep. A static floor with a velocity dragged the box on it like a conveyor belt, a sleeping box with a velocity shot off when woken, and a kinematic platform marked asleep stood still while m2Body_IsAwake reported it awake. A static body made with a velocity of -0, which its def accepts, still restores.
• m2World_Restore refuses a water volume whose box has no area (#325). m2CreateWaterVolume refuses such a box and no call changes it later, so only a snapshot could make one. The volume never acted: a box floating at y -0.2464 sank to y -6.5433. The restore and the create now put the box to the same test.

1.2.1 (2026-11-04)

This release makes a static shape that a host moves into a sleeping body touch it on the next step, and makes m2World_Restore refuse contact pairs the broadphase never makes. No golden line moves, and the snapshot and journal formats keep their versions.

Changed

• Results: no golden line moves (#319). Only a pair that a host call moves out of date gets a new manifold: a static shape moved into a sleeping body it already held a pair with. A pair whose shapes did not really move computes the same manifold as before.

Fixed

• A static shape that a host moves into a sleeping body touches it (#319). The step copies a pair's manifold forward without computing it when both bodies are static or asleep. m2Body_SetTransform and geometry setters such as m2Shape_SetPolygon move a static shape without waking a sleeper it does not touch, so when the two already held a pair, its old manifold stayed. A static wall teleported or widened into a sleeping box reported no contact points, no touching flag and no begin event, and moving the wall again did not wake the box. A pair with a moved shape now gets a fresh manifold, the one the same wall moved in from far away gets.
• m2World_Restore refuses a pair the broadphase never makes (#315): two shapes a mask or a negative group keeps apart, two sensors, two segments, a static shape with a kinematic one, two static shapes with a sensor among them, or the shapes of two bodies a joint without connected collision joins. The step kept such a pair until one of its shapes left its fat box, so the restored world pushed apart shapes the host keeps apart and reported a sensor inside another sensor. Two overlapping boxes pinned without connected collision ended 0.667 m apart after 30 steps with such a pair, instead of 0.6 m. A pair with a moved shape is still accepted, and so is a pair whose shapes drifted apart within their fat boxes.

1.2.0 (2026-11-04)

This release makes a water volume lift a body the same wherever the body is. Far from the world origin, buoyancy used to lose most of its digits: 100 km out, a floating box was thrown hundreds of meters into the air. Four golden lines move, and the snapshot and journal formats keep their versions, but as in every minor release, snapshots and tapes written by 1.1.0 are refused with m2_errorVersion.

Changed

• Results: four golden lines move, the same in the scalar and AVX2 builds (#302): FLUID, ROLLBACK, ROLLBACK_SNAPSHOT and JOURNAL. Each runs a water volume. The golden fluid scene floats two crates in a pool 8 to 16 m from the origin (FLUID, and ROLLBACK, whose world holds the same scene), and the seeded API walk (JOURNAL) drops its bodies into a pool reaching 14 m either side of the origin. At that distance, world-space float sums round differently from body-relative ones, so the forces change in their last bits and the worlds step to other bits. ROLLBACK_SNAPSHOT hashes the bytes of a snapshot of that world; only the values inside it differ. The other nine lines hold. A body near the origin floats as before to within rounding.

Fixed

• A water volume lifts a body the same wherever it is (#302). Each shape's outline was built in world coordinates as 32-bit floats, and the submerged polygon's area and centroid were summed as a triangle fan about the world origin, so far from the origin the terms cancelled. Every outline is now built relative to the body's origin, and the world position enters once, as the 64-bit difference between the surface and the body's height. A 1 m box of density 1 dropped into water of density 2, its height after 120 steps of 1/60 s:

1.1.0 (2026-11-03)

This release changes how m2DecomposeOutline triangulates an outline, so the long, thin triangles its ear clipping cuts no longer drop out of the pieces. Most concave outlines get new pieces of the same area, and fewer of them. No golden line moves, and the snapshot and journal formats keep their versions, but as in every minor release, snapshots and tapes written by 1.0.1 are refused with m2_errorVersion.

Changed

• Results: m2DecomposeOutline returns new pieces for most concave outlines (#299). They cover the same area, and on average there are fewer of them. Compared bit for bit with 1.0.1, 89% of 200,000 random star-shaped outlines of 4 to 16 corners on a 0.1 m grid get new pieces, and 96% of 200,000 such outlines of 3 to 64 corners off the grid. The grid outlines average 3.13 pieces, against 3.62. An outline whose triangulation no flip improves keeps its pieces bit for bit. No golden line moves.

Fixed

• m2DecomposeOutline keeps the thin triangles its ear clipping cuts (#299). Ear clipping takes the ear with the lowest corner index, which can cut a long, thin triangle across an outline. The polygon checks refuse a piece whose area is below 0.001 times its perimeter squared, and when no neighbor could fuse with such a triangle, the decomposition dropped it: a 10-corner outline of 16.62 square meters lost a triangle 4.9 m long holding 0.09 square meters. Between the ear clipping and the merge, the decomposition now flips an inner diagonal when the two triangles that share it form a strictly convex quad and the flip raises the worse of the two. A triangle's quality is twice its area over its longest edge squared; this is Lawson's local optimization, with that quality in place of the smallest angle. Area lost, measured:

The flips always end. On the hardest 64-corner outline measured, a decomposition took 325 flips and 382 µs, against 345 µs without them.

1.0.1 (2026-11-03)

This release keeps every piece of an outline that m2DecomposeOutline splits when three of its corners lie on one straight line, as they do in a sprite outline traced on a grid. No golden line moves.

Changed

• Results: no golden line moves (#296). Only outlines whose merge pass tries a fuse that the polygon checks refuse get new pieces; in a comparison of 400,000 random outlines, each of them lost area or was refused before.

Fixed

• m2DecomposeOutline keeps the pieces of an outline with a straight run (#296). The merge pass fused two pieces when its convexity test, which works in double, found every corner of the union turning left. In float, a corner on a straight run can turn by a hair, so the pass fused pieces across it into one that the polygon checks refused, and the decomposition dropped it along with the valid pieces it was made of. A 6-corner outline of 17.86 square meters came back as one piece of about 5.2. The merge now fuses two pieces only when the union passes the polygon checks. Among 200,000 random star-shaped outlines of 4 to 16 corners on a 0.1 m grid, 521 lost more than 1% of their area and 27 were refused; now none loses more than 1%, and none is refused.

1.0.0 (2026-11-03)

This release settles maul2d at 1.0.0. No golden line moves, and no library behavior changes. What changes is the promise (#293): from 1.0.0, a minor release only adds to the API, a patch release only fixes, and there is no 2.0.0. A release that changes results is a minor release, and its entry says what changes. A snapshot or journal tape is read within the minor version that wrote it and refused across minor versions. The other pull requests in this release change no library code.

Changed

• The 1.y versioning rule (#293): a minor release only adds to the API, a patch release only fixes, and a release that changes results is a minor release whose entry says what changes. Within a minor version, a snapshot or tape replays onto the same bits.
• The binary interface (#293). From 1.0, M2_ABI_VERSION is the major and minor version, the shared library's SOVERSION is 1.Y, and the CMake package accepts any later 1.y. Before 1.0 M2_ABI_VERSION was the whole version, and only the release that wrote a snapshot or tape read it, so 1.0.0 refuses 0.11.4's snapshots and tapes with m2_errorVersion.
• Results: no golden line moves (#281, #283, #285, #287, #293).

0.11.4 (2026-11-02)

This release makes the world queries between steps see every shape where the last step left it. Results change: 7 of the 13 golden lines move, because the world hash covers each shape's broadphase box and moved flag. The simulation does not change: body and particle state is bit-identical, and no format version changes.

Changed

• Results: 7 of the 13 golden lines move, the same in the scalar and AVX2 builds (#278): STACK, CONTACTS, ROLLBACK, JOURNAL, BENCH_CHAIN30 and BENCH_CHAIN2000 hash moving shapes' fat boxes and moved flags, and ROLLBACK_SNAPSHOT's bytes carry the trees and the moved flags, which the end-of-step refit now sets. FLUID, JOURNAL_TAPE, BENCH_PYRAMID15, BENCH_PYRAMID30, BENCH_JOINTFARM and BENCH_WATER hold. test_golden compiled against both versions with m2World_Hash replaced by a hash of only every body's transform and velocities and every particle's position and velocity agrees on 12 of the 13 lines, the seeded API walk and every per-step mix included; the 13th is ROLLBACK_SNAPSHOT, which hashes snapshot bytes. The snapshot and the tape keep their layout, and only the box values and moved flags inside a snapshot differ.

Fixed

• Between steps, a query sees a shape that moved more than its broadphase box's 0.1 m margin in the last step (#278). The step refit moving bodies' boxes at its start, before the pair update, so between two steps every tree still held each awake shape's box from before the last solve. The step now refits them once more at its end, after the sleep pass. The guide's events and queries page says that a query between steps sees each shape where the last step left it. Before and after the change:

0.11.3 (2026-11-02)

This release stops a bullet from passing a wall when more than 64 shapes crowd its path, and makes m2World_CollideMover with a short array hold the planes of the lowest shape slots, whatever order the broadphase trees yield them. No golden line moves.

Changed

• Results: no golden line moves, in the scalar or AVX2 build (#273, #276).

Fixed

• A bullet advances against every shape in its path (#276). It kept only the 64 shapes with the lowest slots among those whose boxes overlap a substep's sweep, and advanced against those alone. Small shapes beside the bullet's lane filled the 64 places, so a wall with a higher slot was never tested: with 400 circles 12 cm from the lane, a 300 m/s bullet flew through a wall it stops at with 200. The bullet now advances against every shape in its sweep that may stop it and keeps the earliest impact, which is the same in whatever order the broadphase trees yield the shapes. When no more than 64 shapes are in a sweep, the bullet stops at the same time as before.
• m2World_CollideMover with an array shorter than the planes it finds holds the planes of the lowest shape slots (#273). It kept the planes the broadphase trees yielded first, then sorted only those. The trees' order follows their history, which the world hash does not cover, so two worlds with the same hash could hand a controller different planes: twelve posts around a capsule, with room for three, kept shapes 1, 2, 3 in one tree history and 1, 3, 4 in another. A short array now holds the planes of the lowest shape slots, in ascending order; the returned total is unchanged, and an array with room for every plane gets the same planes in the same order as before. Its /// block and the guide's events and queries page say so.

0.11.2 (2026-11-02)

This release keeps the contacts of a particle near more than 32 shapes, and speeds up a spring fill. No golden line moves.

Changed

• The spring fill stops its scan a diameter above each particle (#268). m2CreateParticlesInPolygon with m2_springParticle tested every pair of the particles it made, so its time grew with the square of the batch. A fill emits its lattice row by row from the bottom, so for each particle the scan now covers the rest of its row and the row above, fewer than 512 particles. An 80000-particle fill took 2.7 s and now takes 0.011 s (RelWithDebInfo, clang-20). The springs come out the same, in the same order, and the same fills reach the same m2World_Hash before and after.
• Results: no golden line moves, in the scalar or AVX2 build (#268, #271).

Fixed

• A particle near more than 32 shapes keeps the contacts it really has (#271). A particle kept only the 32 overlapping shapes with the lowest slots before testing which ones it touches. Boxes are fattened by 0.1 m, so shapes far from touching filled those places, and a touching shape with a higher slot was never tested. m2Counters.particleBodyContactsDropped did not count it, and when the particle touched the crowd the counter never passed 28. A particle now tests every non-sensor shape whose box overlaps its own and keeps the four touching shapes with the lowest slots; every touch past four counts as a drop. The kept set depends only on which shapes touch, not on the order the broadphase trees yield them. When no more than 32 shapes overlap a particle's box, the kept contacts are the same as before, in the same order.

0.11.1 (2026-11-02)

This release stops two shapes without area from colliding: a segment or a chain segment never pairs with another, as in Box2D. Such a pair could not hold a body anyway: it touched for a step before the body sank through. One golden line moves, and the snapshot and journal formats stay as they were.

Changed

• Results: one golden value moves, M2_JOURNAL_HASH, the same in the scalar and AVX2 builds (#265). The seeded API walk behind it attaches chains to random bodies, dynamic ones included. Their pairs with other segments and chains are no longer made, so the walk's worlds step to other bits. No other golden scene makes such a pair, and their lines hold. The snapshot (version 8) and journal tape (version 9) formats are unchanged.

Fixed

• Two shapes without area never collide (#265). A dynamic segment or chain set down on a segment or chain floor touched it for a step and then sank through: two lines have nothing inside to push each other out of. The broadphase no longer pairs a segment or a chain segment with another. A body that must land on one carries a circle, a capsule or a polygon. A sensor among them still pairs, so a segment sensor still detects a segment crossing it. m2Segment, m2ChainSegment and the guide's bodies and shapes page say so.

0.11.0 (2026-11-02)

This release makes a rollback keep the end events a destroy or a disable queued between steps. To carry them, the snapshot and journal formats change, so 0.11.0 refuses 0.10.0's snapshots and tapes. No simulation result changes.

Changed

• Breaking: the snapshot format is version 8 and the journal tape format is version 9 (#254). A snapshot now carries the end events queued for the next step. 0.11.0 refuses 0.10.0's snapshots and tapes with m2_errorVersion.
• Results: only the two format golden values move, M2_ROLLBACK_SNAPSHOT_HASH and M2_JOURNAL_TAPE_HASH. Every simulation line stays, so the same calls step to the same bits as on 0.10.0.

Fixed

• A rollback keeps the end events a destroy or a disable queued between steps (#254). Destroying or disabling a touching shape between steps queues its contact and sensor end events for the next step. A snapshot taken between the destroy and that step left them out, so restoring it and stepping again never delivered them, and a begin event lost its end. A journal started in that gap lost them on replay too. A restore now brings them back. A snapshot whose queued ends carry another step count, or name a slot outside the shape pool, is refused with m2_errorFormat.

0.10.0 (2026-11-01)

This release makes two kinds of argument refusals stricter, keeps a refused journal replay from changing anything a program can see, keeps host code from destroying the world it runs in, and stops m2ComputeHull from shrinking fine curves. A program that relied on the two old leniencies below needs to change. No golden value moves, so the same calls step to the same bits as on 0.9.0.

Changed

• Breaking: a list read refuses a bad pair of array and capacity, as in maul3d (#231). Only a null array with a capacity of 0 measures now:

A program that measured with NULL and a capacity other than 0 passes 0. m2World_Restore and m2World_ReplayJournal still answer a negative size with m2_errorFormat and no misuse, as for any bytes that are not a snapshot or tape. - Breaking: m2CreateWorld checks the particle settings (radius, density, gravity scale and the eight strengths) even when particleCapacity is 0 (#233). A def with a setting outside its range, NaN included, is refused in a world without particles too. Such a world used to be created and then refuse its own snapshots and tapes with m2_errorFormat. - Results and formats: no golden value moves. The snapshot (version 7) and journal tape (version 8) formats are unchanged. As before 1.0.0, 0.10.0 reads only its own snapshots and tapes, and refuses 0.9.0's with m2_errorVersion.

Fixed

• m2ComputeHull keeps every merged point within 0.01 m of the edge that replaces it (#229). On a dense curve, such as a finely traced sprite outline, the merge used to eat the curve and return a smaller hull with m2_success: 256 points on a unit circle gave an octagon with points up to 0.09 m outside it. A curve that needs more than M2_MAX_POLYGON_VERTICES vertices to stay that close is now m2_errorLimit, as the header says for any hull of more vertices. A hull the old merge built correctly comes out the same.
• A refused m2World_ReplayJournal leaves the event streams as they were (#236). It used to empty the last step's events and drop an end event that a destroy between steps had queued, so a host saw a contact begin and never end.
• A refused m2World_ReplayJournal leaves the counters as they were, except that misuse by host code the replay ran stays counted (#238). It used to leave the last-step counts of the steps it ran before it failed. The m2Counters header and docs/user/diagnostics.md now say which counters a restore leaves: the last-step counts and the cumulative counts are not snapshotted, so right after a rollback the last-step counts still describe the step before it.
• m2DestroyWorld called from host code the world runs (a task hook, a debug draw callback, the allocator) is refused, as every other writer is (#243). It counts one misuse and the world stays. It used to free the world while the world was still using it, and from a free hook during a destroy it freed the world twice.

0.9.0 (2026-10-31)

This release settles the API ahead of 1.0.0. The step and the target transform now return a status. The diagnostics and the water volume take maul3d's names, and the public kinds have fixed sizes. Every call clears its outputs the same way when it fails. A program needs the changes below to build again. No golden value moves, so the same calls step to the same bits as on 0.8.0.

Changed

• Breaking: m2World_Step returns m2Result and is marked M2_NODISCARD (#221). A refused step still changes nothing and counts one misuse, as before; a program now sees the refusal in the status:

Check the status; a refused step leaves the last step's contact events in place. - Breaking: m2Body_SetTargetTransform returns m2Result and is marked M2_NODISCARD (#195). It returns m2_errorStale for a stale id and m2_errorInvalid for a static body or a bad pose. For a dt outside M2_MIN_STEP to M2_STEP_LIMIT, it returns m2_errorLimit and counts a misuse. For a pose too far to reach within M2_SPEED_LIMIT in one step, it returns m2_errorLimit and counts no misuse, since a correct program can meet that. - Breaking: the m2Counters and m2Profile fields take the family's names, as in maul3d (#203). A count ends in Count, work lost without telling the caller in Dropped, and calls refused with a status in Refused:

stepCount keeps its name, and the profile is still in milliseconds. awakeCount now counts only enabled, awake dynamic bodies. awakeBodies also counted static, kinematic and disabled bodies, which never sleep. - Breaking: the buoyancy volume is a water volume, as in maul3d, so its name no longer suggests the particle fluids (#199). Every m2FluidVolume name is now m2WaterVolume: the id, m2_nullWaterVolumeId, the def, m2DefaultWaterVolumeDef, the create and destroy calls and m2WaterVolume_*. m2WorldDef.fluidVolumeCapacity is waterVolumeCapacity. m2WaterVolumeDef takes its box as bounds, an m2WorldAabb, in place of regionLower and regionUpper. m2WorldAabb is now declared in core_math.h. - Breaking: m2CreateWaterVolume refuses a box without area, with m2_errorInvalid and one misuse (#201). A box with area has its upper corner above the lower on both axes; a volume without one could never act. The default def's box is one point at the origin, so set bounds before creating. - Breaking: m2BodyType, m2JointType and m2ShapeType are int32_t typedefs, and m2ParticleFlags is a uint32_t typedef, each with its constants in an anonymous enum (#184). Their sizes no longer depend on the compiler. Code that names enum m2BodyType and the like uses the typedef. The constants keep their names and values. m2ParticleDef.flags is an m2ParticleFlags, and m2Particle_GetFlags returns one. m2IsCpuBackendSupported returns bool, and m2Hash64 takes an int64_t byte count. - Breaking: a call that fails clears its outputs, by the family rule: - Refused list reads zero the caller's array over its whole capacity, instead of leaving it as it was (#183). These are the id lists, m2Shape_GetSensorOverlaps, m2World_GetContactData, the overlap and cast-all queries, m2World_CollideMover and m2World_OverlapParticlesAabb. A read that succeeds still writes only the items it reports. - A failed m2World_Snapshot zeroes its buffer over its capacity, m2_errorCapacity included (#183). A ring of snapshot buffers sizes each one with m2World_GetSnapshotSize first, or snapshots into a spare and swaps it in on success. - The closest casts (m2World_CastRayClosest, m2World_CastCircleClosest, m2World_CastCapsuleClosest, m2World_CastPolygonClosest) and m2Shape_CastRay zero hitOut, with the null shape id, on a miss and on a refusal (#166). A program that kept an earlier hit in hitOut across a miss keeps its own copy. - A call that the world's own host code makes, and that is refused with m2_errorBusy, leaves its count as it was. This covers m2Body_Shatter's countOut (#173), m2World_StopJournal's bytesOut (#178) and m2CreateParticlesInPolygon's countOut (#179). Such a call with a null count returns m2_errorBusy instead of m2_errorInvalid. - m2Body_Shatter fills bodiesOut with null ids on every failure, a null countOut included (#173). - Breaking: m2Shape_GetSensorOverlaps on a live shape that is not a sensor counts one misuse and zeroes the array over its capacity, as for a stale id (#225). - m2World_OverlapParticlesAabb refuses an inverted box, with one misuse and a zeroed list, as m2World_OverlapAabb already did (#201). A flat or one-point box is still a fair query. - Results and formats: the same calls step to the same bits as on 0.8.0, and no golden value moves. The snapshot (version 7) and journal tape (version 8) formats are unchanged. As before 1.0.0, 0.9.0 reads only its own snapshots and tapes, and refuses 0.8.0's with m2_errorVersion.

Removed

• Breaking: m2MinF, m2MaxF, m2AbsF, m2ClampF and m2UnwindAngle are no longer in the public headers (#197). A program uses its own min, max and abs. m2MakeRot still maps any angle into [-pi, pi]. core_math.h no longer pulls <xmmintrin.h> or <arm_neon.h> into a program built with MSVC.

Fixed

• m2DestroyWorld no longer crashes when the allocator's free hook reads the world back (#209). The world is emptied before its first pool is freed, so the hook finds every id stale and every list empty.
• m2World_ReplayJournal refuses a tape with m2_errorFormat when one of its void calls is refused (#217). Before, it skipped the call and returned m2_success. Examples are a velocity edited to NaN and a step edited to a dt of 0. No tape a recording wrote is affected.
• m2CreateParticle and m2CreateParticlesInPolygon refuse particle flags with a bit the library does not define, with m2_errorInvalid and one misuse (#215). A restore refuses undefined bits in particle flags, joint flags and motion locks with m2_errorFormat.
• m2CreateMouseJoint counts no misuse when it refuses a target too far from body B, and returns m2_errorLimit at any rotation of B (#195). Before, a target past the float range with B turned exactly a quarter returned m2_errorInvalid; ordinary targets were never affected.
• m2Body_GetLocalPointVelocity counts one misuse for a stale id instead of two (#192).
• m2CreateWorld refuses, with m2_errorCapacity and before allocating anything, a jointCapacity above 1,073,741,823. Above that, the joint edge count wrapped 32 bits (#187).
• m2World_Hash covers a pool's generations in a world with more than 536,870,911 slots in that pool (#184). Above that, the pool's byte count overflowed 32 bits and its generations dropped out of the hash.
• The dropped-work counters stop at INT32_MAX instead of overflowing (#189). Worlds with more than 2^30 bodies or water volumes no longer overflow in the hash, the free rings or the restore check.

0.8.0 (2026-10-29)

This release renames the API by the Maul family's naming rule, which maul3d follows too. Every change is a rename, so a program builds again once it uses the new names below, and nothing it computes changes.

Changed

• Breaking: these are renamed, with their parameters and meaning unchanged (#159):

The m2WorldDef fields enqueueTask and finishTask keep their names. - Breaking: the body switches are named as in maul3d (#159). A body switched on and off as a whole is m2Body_Enable and m2Body_IsEnabled, and a bullet is a part switched on and off, m2Body_EnableBullet and m2Body_IsBulletEnabled:

m2Body_IsEnabled keeps its name. - Breaking: the shape geometry getters each read one shape type and refuse every other, so they name it (#162):

m2Shape_SetCircle and the other geometry setters keep their names: they take a shape of any type and change it. - The arrays the list calls fill are named with Out in the headers (idsOut, hitsOut, planesOut, overlapsOut, dataOut, piecesOut, and bufferOut for m2World_Snapshot). No call changes. - Results and formats: the same calls, renamed, step to the same bits as on 0.7.0, and no golden value moves. The snapshot (version 7) and journal tape (version 8) formats are unchanged, but as before 1.0.0, 0.8.0 reads only its own snapshots and tapes and refuses 0.7.0's with m2_errorVersion.

0.7.0 (2026-10-28)

This release ends the API audit before 1.0.0. Every change is a rename or a new parameter order, so a program builds again once it follows the items below, and nothing it computes changes.

Changed

• Breaking: the list queries take their filter before what they write, so each one ends with its filter, its array and the array's capacity (#153).
• m2World_CastRayAll, m2World_CastCircleAll, m2World_CastCapsuleAll, m2World_CastPolygonAll, m2World_OverlapCircle, m2World_OverlapCapsule, m2World_OverlapPolygon, m2World_OverlapAabb and m2World_CollideMover take (world, ..., filter, out, capacity). The filter used to come last.
• Move the m2QueryFilter argument from the end to just before the output array. A call left in the old order no longer compiles.
• Breaking: these are renamed, with their meaning unchanged (#149, #150, #151):

A motor's maxMotorEffort is still a torque on revolute and wheel joints and a force on prismatic joints. - Results and formats: the same calls, renamed and reordered, step to the same bits as on 0.6.0, and no golden value moves. The snapshot (version 7) and journal tape (version 8) formats are unchanged, but as before 1.0.0, 0.7.0 reads only its own snapshots and tapes and refuses 0.6.0's with m2_errorVersion.

0.6.0 (2026-10-28)

This release settles most of the API before 1.0.0, so nearly every program needs changes to build against it. Each Breaking item says what to change.

Added

• Three new statuses: m2_errorFormat (-8), m2_errorLimit (-9) and m2_errorBusy (-10), named by m2ResultName (#133).
• Every fixed bound a call checks is now a public constant. M2_MAX_* is a count, M2_*_LIMIT a magnitude and M2_MIN_* a floor. New ones: M2_MAX_OUTLINE_POINTS and M2_MAX_SHATTER_PIECES (64 each), M2_MAX_HULL_POINTS (256), M2_MAX_FILL_COLUMNS (256) and M2_MIN_PARTICLE_RADIUS (0.02 m) (#133, #141).
• Particles are created from a def like every other object: m2ParticleDef and m2DefaultParticleDef (#109).
• New calls (#98, #114, #123):
• m2Joint_EnableConnectedCollision changes a live joint's connected collision;
• m2Joint_EnableSpring turns a distance, wheel or revolute spring on or off;
• m2Chain_IsLoop reads a chain's kind;
• m2DistanceJoint_GetLengthRange reads what m2DistanceJoint_SetLengthRange sets;
• m2Joint_SetConstraintHertz and m2Joint_SetConstraintDampingRatio, with their getters, soften the rows that hold a revolute, prismatic, gear, pulley or ratchet joint together;
• m2WeldJoint_SetLinearSpringHertz, SetLinearSpringDampingRatio, SetAngularSpringHertz and SetAngularSpringDampingRatio, with their getters, tune a weld's two springs;
• a motor joint's drive can change while the world runs.

Changed

• Breaking: refusals return the family's statuses (#133):
• a writer called from host code the world is running (a task hook, a debug draw callback, the allocator) returns m2_errorBusy, not m2_errorState;
• bad snapshot and tape bytes, a world of another shape included, return m2_errorFormat, not m2_errorInvalid, and count no misuse;
• a value past a published bound, infinity included, returns m2_errorLimit, not m2_errorInvalid;
• a NaN, or a value outside its parameter's documented range, is still m2_errorInvalid. Code that compares a status with m2_errorInvalid or m2_errorState needs the new cases.
• Breaking: bounds are renamed, with their values unchanged (#133):

Removed

• Breaking: these have no replacement under the old name:
• m2BodyDef.fixedRotation, m2Body_SetFixedRotation and m2Body_IsFixedRotation: lock rotation with m2MotionLocks.angularZ (#100);
• m2Joint_GetHertz, m2Joint_GetDampingRatio, m2Joint_GetAngularHertz and m2Joint_GetAngularDampingRatio: use the m2Joint_GetSpring* calls (#98);
• m2Joint_SetAngularSpringHertz, m2Joint_SetAngularSpringDampingRatio and their getters: use m2Joint_SetSpringHertz on a revolute and m2WeldJoint_SetAngularSpringHertz on a weld (#123);
• m2DistanceJoint_IsSpringEnabled: use m2Joint_IsSpringEnabled (#114).

Fixed

• A bullet whose only shapes are segments or chain segments no longer passes through thin walls. Such a bullet's results change (#137).
• Circle, capsule and rounded polygon casts give the right hit far from the origin and for very long rays, from about 1e9 m. They used to hit the center line, or report a hit at the ray's origin. A ray starting on a circle's surface hits at a fraction of 0, never slightly below it (#138, #140).
• m2ComputeHull no longer ignores every point after the eighth (#141).
• A particle spring or elastic triad whose ends are farther apart than M2_REACH_LIMIT stays finite, by treating the ends as that far apart. Before, it made the world's particle state non-finite. Nearer links keep their results (#105).

Security

• Recording a create, a particle fill or a shatter no longer writes bytes of the caller's memory into the journal tape. A def's padding and a polygon's normals and unused slots used to reach the tape, so two recordings of the same calls could differ. Every recorded def and polygon is now copied field by field (#107, #116).
• A particle fill, or the replay of a tape carrying one, no longer hangs on a huge polygon. The fill checks its polygon as a shape's and bounds its rows (#102).
• A snapshot whose spring rest lengths or triad corners lie outside what a fill makes is refused with m2_errorFormat, before it changes anything (#105).

0.5.0 (2026-10-27)

Changed

• Breaking: m2CreateWorld refuses with m2_errorCapacity a definition whose world would snapshot to more than M2_MAX_SNAPSHOT_BYTES (1,073,741,801 bytes, about 840,000 shape slots), before it allocates anything. Every world within that size snapshots, restores and records a journal (#92).

• No simulation result changes. The snapshot (version 6) and journal tape (version 7) formats are unchanged; as before 1.0.0, 0.5.0 reads only its own snapshots and tapes and refuses 0.4.0's with m2_errorVersion.

Fixed

• A world's snapshot, restore and journal sizes are computed in 64 bits, and a snapshot is measured with the same per-array sizes the snapshot walk writes and the restore reads, so very large worlds no longer get a wrong size (#92).
• m2Shape_GetSensorOverlaps and m2World_GetContactData measure with a null array at any capacity, as documented; a null array with a capacity above 0 used to crash (#95).

0.4.0 (2026-10-26)

Changed

• Breaking: snapshots and journal tapes are read only by the release that wrote them. Both formats now start with the same 16 bytes as maul3d's: a magic, the writer's M2_ABI_VERSION, the format's own version and the header's size. Bytes from another release, another format version or another build are refused with m2_errorVersion instead of m2_errorInvalid, and so is a tape that starts with another release's snapshot. Before 1.0.0 every release is its own ABI version (#65).
• Breaking: the snapshot format is version 6. It starts with the new prefix, and its magic is stored so that a hex dump reads M2SN. A snapshot written by an earlier release is refused (#65, #76).
• Breaking: the journal tape format is version 7. It starts with the new prefix, its magic reads M2JN in a hex dump, and its set-mass-data record carries the inertia about the center of mass. A tape written by an earlier release is refused (#65, #76, #80).
• Breaking: m2MassData takes the inertia about the center of mass. centralInertia replaces rotationalInertia, which was the inertia about the body origin, in m2Body_SetMassData and m2Body_GetMassData. Pass the inertia about the centroid, as most formulas give it (a disc's is m r^2 / 2), and drop any parallel-axis shift. A small inertia beside a far center is now kept as given: a 1 kg body with its center 1 m from its origin and a central inertia of 1e-10 used to read back as unable to turn (#80).
• Breaking on 32-bit x86: the public structs lay out as on x86-64. Every 64-bit member of a public struct (a position's coordinates, userData, the filter bits, the event steps, the counters) is 8-byte aligned through M2_ALIGN8, so a program built against the old headers on 32-bit x86 must be rebuilt. Other targets keep their layout (#78).
• The mouse joint pulls with a spring of the body's own mass, equally hard in every direction, with stiffness mass (2 pi hertz)^2. A body gripped at its center feels the same pull as before; gripped off its center, it is no longer slack across the arm (#79).

Fixed

• 32-bit x86 builds and gives the same bits as every other target. It did not build, and its tapes would have differed from x86-64's. GCC 14 and Clang 20 on 32-bit x86 are now CI cells (#78).
• A joint that pins a point on a long arm against a small inertia holds it. A 1 kg ball of radius 5 cm on a 1 m revolute pendulum flew about 760 m within 5 s. The joints now build their point mass from the arms each substep reaches, in double, so the revolute and motor joints hold a 1 kg body by a point 1 m from its center within 1 cm while its mass times arm squared over inertia is up to 1e7 (#70). With its inertia stated about the center, the motor joint holds such a body up to 1e8 (#80).
• A rigid weld holds a long arm within 0.25 mm up to a ratio of 1e8: it solves its point and its angle together, where solving them in turn let the anchor sag 1 cm at a ratio of 100 and more than 1 m from 1e4 on. The mouse joint no longer throws such a body: from a ratio of 1e4 on it flung it 90 to 155 m, and now holds it within 7 mm up to 1e7 (#79).
• A joint spring whose hertz is a subnormal float, with a damping ratio of 0, no longer turns every position it touches into NaN on the first step. Such a value is accepted by every def, setter and snapshot, and the bug was in every release since 0.1.0 (#72).
• m2World_Restore refuses a snapshot whose particle springs or triads join a dead particle, where it accepted it and left a world that m2World_Validate refuses (#73).

0.3.0 (2026-10-25)

Changed

• Breaking: the snapshot format is version 4. Snapshots carry 32-bit slot generations and the particle and fluid volume pools' retired counts. A version 3 snapshot, or a tape that starts with one, is refused. A tape's records and header do not change, except the size of the snapshot it starts with, and the journal stays at version 4. The public ids, the API and the ABI do not change. Every golden hash moves, but only because the hash covers the wider generations: hashed at 16 bits, every world hash keeps its old value (#61).

Fixed

• A destroyed particle or fluid volume id no longer names a live object again after 65536 reuses of its slot. A fountain with 1000 particle slots emitting 1000 a second aliased the ids it held after about 18 hours. Every pool now keeps 32-bit generations and retires a slot at its last one, so a pool of capacity n makes n × 2^32 objects over a world's life (about 136 years with 1000 slots at 1000 a second) where bodies, shapes, joints and chains used to run out after n × 65536. A restore keeps the pool's spent budget (#61).

0.2.0 (2026-10-25)

Changed

• Breaking: m2DecomposeOutline refuses with m2_errorInvalid an outline whose pieces all fail validation, such as a triangle 100 km long and 1 cm tall, where it returned m2_success with a count of 0. In both the fill and the measure call the count is left as it was, as for every refusal (#53).
• On AVX2 the solver's min and max are one instruction each, with the same bits. The pyramid bench scenes run faster on GCC 14 (best of nine rounds in each of two runs: pyramid15 8.1 and 8.9 ms before, 7.6 and 7.8 ms after; pyramid30 57.7 and 59.7 ms before, 49.7 and 54.5 ms after), and every bench hash is unchanged. The library is also built with SSE math on 32-bit x86 and the compiler's default trapping math, from the family's shared flags (#56).

Fixed

• m2DecomposeOutline refuses a clockwise outline far from the origin. Its winding test summed the area in float, so near 98304 m a small clockwise hexagon summed positive and split into two pieces. The area is now summed in double (#53).
• Polygon validation accepts small polygons far from their body's origin. It summed the area for its thinness test in float, so m2MakePolygon refused every 0.25 m to 2 m box and right triangle at 65536 m and 98304 m, most of them at 10000 m, and one at 1000 m. m2ComputeHull, the pieces of m2DecomposeOutline, the shape constructors, m2Shape_SetPolygon, m2World_ShatterBody and restore all go through the same check. The area is now summed in double, against the same threshold (#53).
• A body woken and put back to sleep before a step end, by a long step that moves it or by a teleport followed by m2Body_SetAwake(false), refreshes its contacts. It kept its old sleep streak, so its pairs kept the manifold from before the move: in the reproduction the contact points sat 0.4 m behind the box. The streak now starts from zero wherever a body is put to sleep (#51).

0.1.1 (2026-10-25)

Fixed

• A static shape whose geometry a setter changes (m2Shape_SetCircle, m2Shape_SetCapsule, m2Shape_SetPolygon, m2Shape_SetSegment) collides over its new extent. Its broadphase box used to keep the old extent, so a ball dropped over the new part of a widened static box fell through it. On a dynamic body the box is refitted one step earlier than before, with the same result. The world hash differs from 0.1.0's after such a change, since the box is part of it (#48).
• A restore holds each number that a def, a setter or a tape holds to a range to that same range, and checks each joint kind's own fields with that kind's validators. A snapshot from outside could restore values that turned the world invalid in its first step; such a snapshot is now refused, changes nothing and counts nothing. A snapshot a world writes still restores, and neither format version changes. Two solver paths could store an impulse one float past its limit; both now store the limit (#45).
• A restore refuses a snapshot in which a shape of a static or sleeping body lies outside its broadphase box. Such a snapshot left the step, and the host's queries, finding the body where it was not. So that a world's own snapshots keep restoring, a body's boxes are refitted where it falls asleep, both in the step and in m2Body_SetAwake(false). The world hash can therefore differ from 0.1.0's when a body falls asleep past its box margin; in no golden scene does one (#49).

0.1.0 (2026-10-25)

Changed

• Breaking: the family API shape. m2World is an opaque pointer, and m2CreateWorld(def, &worldOut) returns an m2Result. Every call on a world's objects takes the world first, and readers take const m2World*. Ids are {index1, generation}, with no world field. Creates, destroys, snapshots, restores, the journal calls and the polygon builders return an m2Result and write through Out parameters. The world table, m2WorldId, m2World_IsValid, the *_GetWorld getters, m2SetAllocator, m2SetAssertHandler, m2LastResult, m2_errorConfig and m2WorldDef.workerCount are removed. The allocator is part of m2WorldDef, which begins with its cookie and an ABI version that m2CreateWorld checks (m2_errorVersion). Worlds share nothing, so separate worlds may be created, stepped and destroyed on separate threads. (#12)
• Breaking: misuse counting. m2Counters.misuse counts the calling code's bugs: an invalid argument, a stale id, a writer called from host code. A stale id counts one misuse in every call, while a stale particle id counts nothing, since particles die on their own. Corrupt snapshot or tape bytes count nothing. Host code a replay runs (the task hooks and the allocator) counts like any other caller. Motor and limit calls on a joint without a motor or limit change nothing and count one misuse; for a distance joint, use m2DistanceJoint_SetLengthRange. (#13, #14, #15)
• Breaking: ranges. Defs, setters and tapes refuse values past the ranges in base.h, each listed in docs/user/limits.md: speeds up to 1e5 m/s, masses from 1e-9 to 1e12 kg, time steps from 1e-6 to 10 s, M2_JOINT_REACH of 1e9 m, and the rest. These are the other refusals:
• Body-local lengths beyond M2_HUGE (1e5 m) in shapes, chains, outlines and joint defs.
• Substeps: more than M2_MAX_SUBSTEPS (64) in m2World_Step.
• Body defs with a non-finite value, an unknown type, a negative damping or a zero rotation, and world defs with a non-finite gravity or particle setting.
• Velocities on a static body.
• Negative dampings, which used to be stored as 0.
• Mass data whose fields do not fit together in m2Body_SetMassData.
• Outlines: m2DecomposeOutline refuses an outline that touches itself, or one whose vertex comes within 0.005 m of an edge it does not end.

(#17, #22, #23, #24, #25, #26, #32, #34, #40) - Breaking: what a restore or replay accepts. m2World_Restore refuses a snapshot in any of these cases, and leaves the world as it was: - its arrays do not fit together (free queues, shape lists, owners, broadphase trees); - it holds shape geometry the world would not build; - its mass data is not what the body's shapes give it; - a body rotation in it is not of unit length.

Replay refuses a tape record whose bool flags are not 0 or 1. Snapshots are format 3 and journal tapes format 4, so those written by 0.0.1 are refused. (#23, #27, #29, #31, #39) - Breaking: the world hash. m2World_Hash and m2World_GetHashParts now also cover: - every setting the step reads; - the live slots, keyed by index; - the id pools; - the broadphase's fat boxes.

So two worlds with the same hash step on to the same bits. Every hash value changes, and m2WorldHashParts gains a volumes part. Queries capped at a number of hits keep the lowest shape slots, so they choose the same shapes in every world that hashes the same. (#37, #38) - Breaking: m2World_ShatterBody returns an m2Result and hands the count back through countOut, and m2IsNormalizedRot returns bool. (#19, #20)

Added

• m2DistanceJoint_IsSpringEnabled reads a distance joint's spring toggle back. (#21)

Fixed

• The host's floating-point setting. The library computes in its own setting (round to nearest, subnormals kept, every exception masked) on any host thread. A thread left in flush-to-zero, denormals-are-zero or another rounding mode therefore gets the same bits. Task hooks, draw callbacks and the allocator run in the host's own setting. (#44)
• Saturation in the step. Every velocity saturates at M2_MAX_SPEED, and every joint and contact impulse at M2_IMPULSE_LIMIT, and water and wind loads at M2_MAX_FORCE. A 2x2 joint solve whose couplings would overflow solves its rows one at a time instead. (#42)
• Far-apart joints. A joint between two bodies far apart clamps its separation to M2_JOINT_REACH, where it used to leave NaN in the bodies. (#35)
• Rotations. Normalizing a rotation keeps its direction for any finite nonzero input. Very long, very short or infinite components used to give {0, 0}, NaN or the identity. (#23)
• Far particles. A particle far beyond the grid's reach no longer overflows its cell coordinate. (#28)
• Polygons. A created or set polygon is rebuilt from its vertices, so its normals are always the world's own. (#31)

[0.0.1] - 2026-09-24

The first release of the reworked library.

Added

• m2Counters.pairOverflow: body pairs dropped by the last pair update because the pair table was full. Dropping pairs used to be a debug-only assert.
• bench/: benchmark scenes that time Maul2D and pin their final world hashes in bench/pins.txt. CI fails when a pin moves.
• MAUL2D_BUILD_SHARED builds a shared library. Public functions carry the M2_API export macro and everything else is hidden.
• test/hashes.txt holds the expected determinism hashes, and tools/check_hashes.py compares a test run with them, so a change that moves a hash the same way on every platform is caught too.
• The library target requires C11 of its consumers through CMake, and a test compiles the umbrella header as C++ so the API stays usable from C++.
• Test for contacts past the last graph color (a plank carrying 40 boxes).
• Test for the floating draft of a circle, a capsule and a rounded box at half the water's density.
• m2WorldDef.enableSleeping sets the sleep master switch at creation (default true), as in Maul3D.

Changed

• The version history restarts at 0.0.1. Earlier numbered releases were withdrawn.
• Refusing a caller's input no longer asserts in debug builds. M2_ASSERT is kept for internal invariants; every refusal instead records its reason for m2LastResult and, for a stale or wrong-kind id, counts in m2Counters.misuse.
• The CMake options follow one family scheme: MAUL2D_BUILD_TESTS, _BUILD_SAMPLES, _BUILD_BENCH, _BUILD_TOOLS, _BUILD_TESTBED, _BUILD_SHARED, _INSTALL, _WERROR, _SANITIZE, _TSAN and _COVERAGE. Tests, samples, benchmarks and tools default to on only when the project is built on its own, not when it is added with add_subdirectory.
• Warnings are errors only with MAUL2D_WERROR=ON (CI turns it on), so a newer compiler no longer breaks a consumer's build.
• The CMake modules in cmake/, the package config template and the pkg-config template are shared with the sibling engine. The pkg- config file is relocatable and no longer lists a thread library the engine does not use.
• Every test suite uses the shared test/test_harness.h instead of its own copy of the check macro.
• CI is the family workflow shared with Maul3D: every test suite runs on every cell through CTest, hashes are compared across cells and with test/hashes.txt, and clang-tidy, the package consumer and a shared-library build are checked on every push. Releases ship Linux (x64 and arm64), macOS and Windows packages; the portable x64 package is gone, build with -DMAUL2D_SIMD=scalar instead. The documentation site now carries the guide, the API reference and the changelog, and the browser testbed moves to /testbed/.
• The public maul2d/math.h header is now maul2d/core_math.h, so it can never shadow the C library's math.h when include/maul2d lands on an include path.
• The world's arrays are described once, in a table in src/world_state.c. Allocation, release, the snapshot walk and the memory footprint all read that table, so adding an array touches the struct and one table row instead of seven places. m2World_MemoryBytes now also counts the broadphase trees and the solver scratch.
• m2World_Step with a non-positive dt or fewer than one substep, and the joint parameter getters on a stale id, now refuse with m2_errorInvalid in every build instead of asserting in debug builds. A getter asked for a parameter its joint kind lacks refuses exactly once.
• The journal's op codes and payload structs live in one internal header shared by the recorders and replay, and replay dispatches through a command table instead of an 800-line switch. The wire format is unchanged.
• Each joint type lives in its own src/joint_.c: its def defaults, creation, type-specific API and solver rows, reached through a kind table instead of type switches. Joint types, joint flags and motion-lock bits are named constants. Results are bit- identical.
• m2World groups its 248 fields into per-subsystem blocks (bodies, shapes, joints, chains, particles, volumes, broadphase, contacts, solver scratch, events, recorder), and world_internal.h holds only that layout: cookies, kernels and helpers moved to their module headers, with new distance.h, island.h, ccd.h, buoyancy.h and query.h. maul2d/base.h includes like Maul3D's. Results are bit-identical.
• The step reads as its stages: m2World_Step and m2SolveStep hand their passes (the event window, hibernation, proxy refits, touch events, particle aging, velocity and position integration, joint breaks) to named functions. A length rule now holds functions to 80 lines and source files to 1000: tools/check_lengths.py runs in CI, and the existing exceptions sit in tools/length-exceptions.txt with their reasons and a ceiling that may only shrink. Results are bit- identical.
• Comments no longer carry development-history markers (slice and rule codes, issue numbers, format versions); tools/check_comments.py enforces the conventions.md rule in CI next to the length rules.
• m2MakeRot and m2Atan2 are the engine's own: sine and cosine from a two-part pi/2 reduction and Taylor series, atan2 from an argument- halving identity and a Taylor series, accurate to about 4e-7 instead of the previous 2e-3. Every golden hash and bench pin was re-pinned (identical across gcc and clang, Release and Debug). docs/references.md lists the published sources behind the algorithms.
• The broadphase tree is rewritten: surface-area-guided insertion, strict AVL balance and moves that keep the proxy index without touching the free list. Every golden hash and bench pin is unchanged.
• Contact manifolds, ray casts, convex hulls, shape mass and the distance and shape cast kernels are rewritten from published sources (docs/references.md). Hashes and bench pins move; the pyramid bench settles exactly as before.
• Contact solver rewritten: one lane kernel runs every stage, and the graph-color overflow goes through the same kernel one constraint at a time instead of a separate scalar path. The soft push limit now applies to the scaled bias, so every contact pushes out at most 3 m/s. Contact points alternate their solve order each substep, which removes most of the sideways drift of dropped stacks (the 30-row pyramid top drifted 8.6 cm, now 0.1 cm).
• Joint solver rewritten on scalar rows: each joint kind builds its rows (a Jacobian and a drive: rigid, held, spring or limit) from the pose the substep reached, and one row solver, a coupled-pair solver and a closed-form point pair serve all eleven kinds. Joint rows now follow the bodies' rotation within a step (arms, slide axes, rope directions and lengths), the distance and pulley ropes use their exact current length, and a singular coupled pair falls back to its rows one at a time instead of being skipped. Joint-heavy scenes run about 10% slower for now.
• The step reads as its stages: prepare, the substep (forces, warm start, biased solve, integrate, continuous, relax), then bounce, store and joint breaks; per-body integration split into velocity caps, locked axes and the pose update. Results are bit for bit unchanged.
• Particle neighbor pass rewritten (src/particle_pairs.c): particles sorted by cell are cut into one run per occupied cell, and each cell pairs with itself and the four cells ahead of it in key order. Pairs now come out cell by cell; the pair set is unchanged.
• Buoyancy volumes rewritten: a shape's immersion (area and centroid) comes from the exact circular segment or from clipping its outline at the surface; lift, drag and spin drag apply per body and volume.
• Particle model rewritten on double density relaxation (Clavet et al. 2005) applied to velocities: density and near density from the pair weights q^2 and q^3, walls counting as neighbors; pressure above the rest density of the fill's square packing; cohesion below it and near pressure for tensile particles; powder spacing push; XSPH shear for viscous particles; approach damping linear and quadratic in the approach speed; shape-matched elastic triads and spring nets. Body contacts moved to particle_contacts.c. A tensile droplet now settles at the spacing where cohesion meets its near pressure.
• World def: particleTensilePressureStrength and particleTensileNormalStrength become particleCohesionStrength and particleNearPressureStrength; the default particlePressureStrength is 0.2 on the new pressure scale (water packs as densely as before).
• Mover kit redesigned: m2World_CollideMover fills m2MoverPlane entries; m2SolveMover returns the translation closest to the wish that no plane blocks, found exactly by trying the planes it may rest on, with a bitmask of the planes it rests on; m2ClipMoverVelocity strips the velocity pointing into those planes. m2CollisionPlane, pushLimit, m2SolvePlanes and m2ClipVector are gone.
• THIRD_PARTY.md now lists only the testbed's raylib: every kernel once adapted from Box2D, LiquidFun or Chipmunk2D has been replaced by the engine's own code, and a token-level similarity scan against those projects finds nothing beyond trivial shared idioms. The README credits the published work in docs/references.md; comments and docs that measured the engine against another engine now state its own rules.
• Joint point pairs take their mass inverse once per step at the prepare arms instead of rebuilding and inverting it every pass (chain scenes about 7% faster), and the pose update runs the rotation helpers inline; the public m2MakeRot, m2MulRot, m2NormalizeRot and m2UnwindAngle are the same inline code, so rotations are bit for bit unchanged.
• m2Hash64 hashes eight bytes a round (xor, multiply by an odd constant, fold the high half) and the leftover bytes one at a time, instead of FNV-1a over every byte: about three times faster on a whole world. Every hash value changes; the golden hashes and bench pins are re-pinned, and gcc, clang and Debug agree.
• Public names follow the family rules: m2Aabb, m2AabbResult, m2World_OverlapAabb, m2World_OverlapParticlesAabb, m2Shape_GetAabb, m2Body_ComputeAabb and the drawAabbs flag spell the acronym as a word; m2Shape_CastRay, m2World_GetJournalBaseSize and m2World_GetHashParts lead with their verb; m2World_GetMemoryUsage returns an m2MemoryUsage, as in Maul3D. Forces and impulses take Maul3D's names: m2Body_ApplyForce and m2Body_ApplyLinearImpulse act at the center of mass, m2Body_ApplyForceAtPoint and m2Body_ApplyLinearImpulseAtPoint at a world point.
• m2SetAllocator takes Maul3D's hooks: alloc(size_t bytes, void* context) and free(memory, context) with one context pointer, both or neither (a half pair is refused). The alloc hook may return uninitialized memory; the engine zeroes it.
• Object ids carry their world's generation: the world field (was world0) holds the world slot in its low M2_WORLD_SLOT_BITS bits and the low bits of the world generation above them, so a world recycling a slot refuses the ids of the world before it. An id naming no live world now records m2_errorInvalid (it returned silently before). M2_EVENT_HASH and M2_JOURNAL_HASH, which digest raw ids, are re-pinned; gcc, clang and Debug agree.
• Collision and query filters are 64 bits wide, as in Maul3D: categoryBits and maskBits in m2ShapeDef, m2ChainDef, m2QueryFilter, m2ExplosionDef and m2Shape_SetFilter/GetFilter are uint64_t, and the default mask is UINT64_MAX. The journal records the wider fields, so M2_JOURNAL_HASH is re-pinned; gcc, clang and Debug agree.
• Lifetime functions follow the family form P + Create/Destroy + Object: m2CreateFluidVolume, m2DestroyFluidVolume and m2DestroyParticle (were m2World_CreateFluidVolume, m2World_DestroyFluidVolume and m2World_DestroyParticle).
• The snapshot header holds only the magic, the format version, a build configuration hash and the six world capacities, as in Maul3D. Step count, gravity, wind, the pair count and every pool cursor are state table rows, checked before any byte lands; a snapshot from another build is refused with m2_errorConfig. M2_JOURNAL_HASH, which covers the embedded snapshot, is re-pinned; gcc, clang and Debug agree.
• Shared code follows ADR 0004: src/hash.c holds the hash in both engines, src/simd.h and src/cpu.c are the same file in both once the prefix is renamed, and tools/check_family.py checks the shared files against the sibling repository (byte for byte, or after the rename for tools/family-renamed.txt) in the weekly CI job.
• src/simd.h gains the equality, division, square root and mask-and lanes Maul3D's kernel uses, so both engines carry one SIMD header.
• The README says no language bindings ship yet, and points to Maul3D's C# starter kit for the pattern; CI runs the bindings check where a repository has bindings.

Removed

• m2SetLastResult from the public header. It was internal.
• The dual-backend harness and the MAUL2D_BENCHMARKS option, along with the performance comparison in the README that relied on them.
• m2AssertFail and the M2_ASSERT macro from the public header. They are internal; hosts keep m2SetAssertHandler.

Fixed

• The broadphase checked every candidate pair against every joint in the world to decide whether jointed bodies may collide. Each body now keeps a list of its joints, so the check costs the body's joint count. A 2000-link revolute chain steps 2.2 times faster, and m2Body_GetJoints and body destruction no longer scan all joints.
• Queries documented as safe to call from many threads at once shared one world-owned scratch buffer, so concurrent readers could corrupt each other's results. Tree walks now run on a cursor that lives on the caller's stack, and overlap queries keep their sorted results directly in the caller's array. A four-thread reader test covers it.
• m2World_CastRayAll and m2World_CastCircleAll silently kept at most 64 hits even when the caller's array was larger. They now keep as many as the array holds.
• Journal replay is now atomic: a tape that fails part way, whether truncated, corrupt or recreating an object under a different id than the recording saw, is refused and the world is rolled back to where it was. An id mismatch used to be a debug-only assert, so release builds replayed onward into a different world.
• m2World_Restore refuses a snapshot whose header counters point outside the world's capacities before overwriting anything, instead of indexing past the arrays afterwards.
• A moving shape met at most 256 others per tree in the broadphase and silently ignored the rest. The tree walk now has no fixed limit.
• When both shapes of a pair moved, the pair was collected twice before duplicates were removed, so a nearly full pair table could drop pairs that fit. Each such pair is now recorded once.
• The pair merge wrote its output into the top of the same buffer it was still reading candidates from. With a nearly full table it could overwrite unread keys. It now merges into a buffer of its own.
• m2LastResult was set by only a handful of refusals and lived in one process-wide slot. Every refusal now records its reason (invalid input, full pool or allocation failure, unsupported CPU) and the slot is per thread.
• The misuse counter was incremented without synchronization from reader-class calls, a data race when readers run in parallel. It is now updated atomically.
• The generated API reference merged declarations that followed a trailing comment into the previous entry, so it listed 276 functions where the headers declare 289. tools/gen_api.py now parses each declaration on its own and is shared with Maul3D.
• Input checks that tested x == x let infinities through. They now use finite checks, so infinite positions, velocities and parameters are refused like NaN.
• The public headers used _Static_assert, which C++ and MSVC's default C mode reject, so a consumer that did not ask for C11 could not include them. The layout checks moved into the library's own sources.
• The CPU check that lets an AVX2 build refuse to run on an older CPU was compiled with the AVX2 flags itself, so the compiler was free to use AVX2 instructions before the check ran. It now lives in src/cpu.c, compiled without the backend's architecture flags.
• MSVC on arm64 ignores the /fp:contract- switch, so floating-point contraction was not reliably off there. Every source now turns it off with #pragma fp_contract(off) under MSVC, and the switch is only passed where the compiler knows it.
• Joint, shape and body parameter setters validate in one place for live calls and replay: non-finite or out-of-range values (a NaN motor speed or gear ratio, unordered limits, a negative max motor, an infinite friction) and parameters the joint kind lacks are refused and counted, where several were accepted before. A tampered journal channel byte is rejected instead of asserting in debug builds or writing an unrelated field; a stale m2DestroyJoint or shape setter now refuses; journal start, stop and replay record a reason when they fail (m2_errorConfig for a tape from another world shape); a failed shatter replay no longer leaks its pieces.
• The shape casts, overlaps, sweeps and m2World_FillPolygonWithParticles copied or read a caller polygon's vertices up to its count without a bound, so a count above M2_MAX_POLYGON_VERTICES overran a stack buffer; a NULL circle, capsule or polygon crashed. Every query now builds its proxy through one checked path and refuses bad shapes, non-finite poses, rays and boxes, and non-unit rotations.
• Body velocity, force, impulse, torque and teleport setters, gravity, wind drag, density, chain materials, motor offsets, mouse targets and particle lifetimes refuse non-finite values, which could poison the whole world; m2Body_SetTransform also refuses a non-unit rotation, which it stored as given and which sheared the body.
• m2World_Step refuses an infinite dt.
• Joint creation validated the bodies and the cookie but none of the def's numbers: a NaN or infinite anchor, axis, offset or target, a negative stiffness, damping or budget, an inverted limit or length range, or a correction factor outside [0, 1] was accepted and fed to the solver. Every joint kind now checks its def and refuses such input.
• m2World_Restore checked the header but trusted the arrays: a corrupted snapshot could carry out-of-range body, shape, joint, particle or tree indices, an oversized polygon count, invalid flags or non-finite state straight into the world. Every snapshot block is now checked against its description in the state table before any byte lands; a failed check refuses (m2_errorConfig for another build or world shape, m2_errorInvalid otherwise) and leaves the world untouched. m2UnwindAngle no longer asserts on angles beyond 1e6 radians; it returns the documented clamped boundary.
• m2World_ShatterBody reports m2_errorCapacity when the world cannot seat every piece, and refuses a malformed piece polygon up front. Before, a full world returned 0 silently and a bad polygon left a shapeless piece body behind.
• m2CreateChain checks its points first: a NaN point or a zero- length segment is refused as m2_errorInvalid (before, the segments were built unchecked), and a full chain or shape pool is m2_errorCapacity instead of m2_errorInvalid. A chain that builds no segment no longer burns a chain id, which made a replay of the session mint different ids.
• Shape defs refuse an infinite density or friction and a NaN or infinite tangent speed.
• Capsule rotational inertia missed the offset of the end caps' centroids, and rounded polygons had the mass of their unrounded core. Both now match their closed forms.
• A ray starting inside a rounded polygon reported the exit point as a hit; it now hits at fraction 0 with a zero normal, like every other solid shape.
• GJK reported rounding noise as a small positive distance, with a noise normal, when the origin fell on the simplex of overlapping cores; it now reports the overlap.
• Buoyancy volumes ignored a rounded polygon's radius when measuring its submerged area, so rounded shapes floated too low or sank: a rounded box of half the water's density sank to the bottom. Rounded polygons and capsules now become polygons whose corner fans keep the true area, instead of a sharp core or a bounding-box fraction.
• A graph color stopped taking contacts at 256, a leftover of an old packing buffer, and every contact past it went to the serial overflow: in a 4000-box pile 87% of the contacts solved one by one. Colors now take any number of contacts; that pile steps in 3.4 ms instead of 5.9.