fix(physics): jolt static vectors being freed

[Dhruv-0-Arora]

Task

Preventing memory corruption bug.

Symptom

Jolt.Vec3().Normalize() stores the result in a static temp memory allocation for all vectors. This means that if you do

a = Jolt.Vec3().Normalize()
b = Jolt.Vec3().Normalize() // overriding `a`

then the value of a is overridden by the value of b.

this also is the case with the functions

AddRVec3() & Add()

Solution

Copying the values into a new Jolt.Vec3() through the new ownVec3() function.

This, however, requires that the return value of functions such as getPerpendicular() must be destroyed

const normalAxis = getPerpendicular(constraintAxis)
settings.mNormalAxis1 = settings.mNormalAxis2 = normalAxis
JOLT.destroy(normalAxis)

instead of

settings.mNormalAxis1 = settings.mNormalAxis2 = getPerpendicular(constraintAxis)

-> this version leaks the vector from getPerpendicular

More information below and test file to show concept above in more depth:

Details

Testing file:

JoltOwnership.test.ts

Task

Jolt.Vec3 is stored in heap but
anything a bound method returns by value (Normalized(), AddRVec3(), Add()) is not allocated. the binding keeps one static per method.

How it looks:

Vec3* emscripten_bind_Vec3_Normalized_0(Vec3* self) {
    static Vec3 temp;             // one slot, reused forever
    temp = self->Normalized();    // 16 bytes overwritten, no malloc
    return &temp;
}

So, we instead will copy the values from this memory and store it in a heap allocated Jolt.Vec3 for safer memory management. This means, however, that these Jolt.Vec3 s will need to be Jolt.destroy(x) ed.

Symptom

createAnchorPoint returned jointOrigin.AddRVec3(...) straight through, so callers got a static temp. PhysicsSystem freed it in four places: two JOLT.destroy(anchorPoint) on the ball constraint path, and two convertJoltRVec3ToJoltVec3(anchorPoint) whose destroy param defaults to true.

the function JOLT.getPointer() shows that AddRVec3 returns 54992 every call, malloc's block (heap) starts around 1157600. all four were freeing a data segment address (meaning they did nothing).

In addition

settings members are declared by value (RVec3 mPoint1;), so setters memcpy and the struct never takes ownership. JOLT.destroy(settings) won't free a vector you assigned in, but you can destroy it yourself right after assigning. we were dropping wheelPos, the four urdfWheelBasis vectors, and minBounds/maxBounds.

Solution

1. new ownVec3/ownRVec3 helpers so no static escapes the expression that made it. createAnchorPoint and getPerpendicular now return owned heap vectors
2. destroy the leaks above, plus anchorPoint now that it's real memory
3. JoltOwnership.test.ts pins down both halves: fresh address per malloc, recycling on destroy, the static below the heap, 2000 calls yielding one address, the clobber, and structs copying bytes in

testing

JoltOwnership.test.ts passes in chromium + firefox

[azaleacolburn]

Also could you not write your pr descriptions with claude please, it's just like a really annoying style

[azaleacolburn]

Also, please use the pr description template in the future

[BrandonPacewic]

I have mixed feelings about this pr. While it is true that we were not aware of this behavior there is no bug associated with these changes. (Specific to the static alias function return behaviour of course.)

I believe that #1434 will fix all the other memory changes addressed in this pr so those are not needed here (#1434 addresses a much larger scope of issues which is why I'm saying that it should take priority of fixing the other issues listed in this pr).

Adding a small comment to the top of this particular function (createAnchorPoint) seems warranted, generally do not want the other changes presented here imo.

With that being said #1434 does add this small comment addressing this side effect so I'm unsure of what to do with this pull request in that case:

synthesis/fission/src/systems/physics/ConstraintSettingsUtilities.ts

Lines 9 to 11 in 4968b04

	// Returns a STATIC_ALIAS `RVec3.AddRVec3()`'s scratch buffer.
	export function createAnchorPoint(jointInstance: mirabuf.joint.JointInstance, jointDefinition: mirabuf.joint.Joint) {
	const jointOrigin = jointDefinition.origin

[Dhruv-0-Arora]

Note: this change from returning a Jolt.RVec3 to a Jolt.Vec3 is not in #1434