Vector Math

[luanpotter]

We have explored in the past replacing Vector2 and others from the vector_math package with a records based approach. The issue right now is that allocating Vector2's can be expensive within the game loop, and that forces people to write very non-ergonomic vector math code, for example, instead of being able to cleanly write something like:

position = size / 2 + offset + velocity * dt;

you would need consider saving these to fields and updating them:

position = (size / 2)..add(offset)..add(velocity)..scale(dt);

We have explored using records in the past as they require no allocation and are treated like two floats in memory, but I recall @renancaraujo has found some issues. I think it is time we revisit those issues to see if they still exist and explore other possibilities before committing to Vector2 for V2.

[renancaraujo]

The issue I found was that basically: records can't be mutable. That alone makes some common gameloop operations up to 10 times slower

[luanpotter]

My hope would be that yes they are no mutable but also not allocated, so "mutating" them eg

position += (1, 0)

should be completely equivalent to

positionX += 1
positionY += 0

So in a sense since they are transparent groupings and not allocated, mutating them is not a thing (you are just mutating the variables inside which are mutable). Is that not the case?

[renancaraujo]

if positionX and positionY are mere pointers (var positionY and var positionX) when yes, these are equivalent.

[luanpotter]

they'd be ints, I'd hope they'd be in the stack, not in the heap. similar for structs/records

[renancaraujo]

We can explore the usage of a extension type based solution where extension types would wrap optimized List<double> subtypes.

[spydon]

Now I've tested lot's of alternatives, and all sensible alternatives seem to point to moving away from the vector_math library.

So I think we should move Vector2 (probably need a new name bleeeh, or not then the migration will be smoother) out of vector_math into a small pure Dart package of our own, shared by Flame and Forge2D.

Structure

• Vector2 in the package: a plain class with two double fields (full double precision), the same mutating API as today (add, setFrom, scale, x =, ...), operators + - * / that return a new vector but are inlined so the VM's allocation sinking removes temporaries that never escape, structural ==/hashCode/toString, and an empty onChanged() hook called after every mutation. No Flutter dependency, so Forge2D can use it directly and flame_forge2d keeps the same type on both sides with no conversion.
• NotifyingVector2 extends Vector2 in Flame: overrides onChanged() with a single-listener notifier and a version counter, and Transform2D reads the versions instead of subscribing. This is what position, size and scale are, and since it is a Vector2, everything mixes freely.

Efficiency (AOT, ns per component per operation, measured)

• position = size / 2 + offset + velocity * dt: 28 today with vector_math's operators (six allocations, two per operator) → 5.7 with the same code, no allocation. The chained ..setFrom()..scale()..add() form we write today to avoid that costs 15.
• position += velocity * dt: 14.5 today (allocates) → 5.8, no allocation.
• position.addScaled(velocity, dt): 18 today → 4.2.
• position.x = v: 16 today → 3.6.
• Notifier overhead over a bare two-double class: under 1 ns. Web (dart2js): 22 → 12 ns for the full expression.
• Those allocations also decide how often the GC runs: in a loop-shaped test with live objects around, the vector_math version triggered 17x more scavenges. That cost lands as pauses on other frames, not on the vector code itself, so the numbers above understate it.

Ergonomics

• One type. position = size / 2 + offset + velocity * dt and position += velocity * dt are now the fast form, not the slow one, so the mutating chains (..setFrom()..scale()..add()) become optional.
• size.addListener, size.x = 32, position.add(v), position.setFrom(v) stay exactly as they are.
• Vector2(0.1, 0).x == 0.1, and == compares values.

Whatcha think?