Spring animation is a fairly new technique for animating stuff going between two points. It works by simulating a real physical spring, which gives you a really nice and responsive animation.

The difference maker here is that the spring is physically based, so it always feels “right” to creatures of Earth.

In fact, springs feel so right that they’ve seen widespread adoption in UI toolkits. If you’ve used an Apple product it’s everywhere, Android has had the DynamicAnimation library since 2019, and react-spring has been around for at least that long as well.

How many different springs do you spot? It’s more than 4.

Maybe check out this interesting article for a sort-of history of spring-based animation.

Games haven’t seen nearly as much adoption though. It’s common to animate cameras using springs, but otherwise they still feel like a bit of a secret. I feel like an obvious application is to apply them to game object transforms for some convenient, flexible, good looking animation, but I really couldn’t find much of anything out there. So I made this post.

Specifically I’m referring to Unity-style transforms, with separate translation, rotation, and scale components.

The main spanner-in-the-works when building a Spring Transform is applying springs to quaternions, but this ends up not being such a big deal in the end.

This post and the provided code will be Unity-like, but the concepts are easily applicable everywhere.

The Use Case

The use case for this is basically any transition that wants animating, but the real win is for interactive elements:

• Doors/door handles/drawers.
• Switches/buttons/levers.
• Level editors (moving, rotating pieces).
• Procedural animation (look-at systems, gun reloads, etc).

The procedural animation case is a bit open ended, but these examples all feel a lot better when they respond well to interruption, which is the spring’s specialty. The other bonus is that you don’t need to track any additional state for whether the door/lever/switch is open or closed — just tell it what to be and let the spring handle the rest.

What About Tweening?

Something that does have widespread use in games is (inbe)tweening, otherwise known as easing. There are many libraries that accomplish this for all major and minor game engines:

• PrimeTween (Unity)
• Tween (Godot – Built-In)
• Fresh Cooked Tweens (Unreal)

My gripe with tweening is that it’s non-trivial to interrupt a tween and have it react in natural way. Most applications just reset the tween to the beginning each time (yuck), or worse: force you to wait until the end of the tween to use the element again (guck).

Tween resetting on each click, yuck.

Sometimes, developers say “I can fix that”, and have gone to great lengths to make the tween react “smoothly”;

A demo from InTween where they’ve used some smoothen() magic to try to handle spamming inputs.

No matter your determination, it just never quite works right. In this one, the tail end of the animation has a noticeable curve after multiple clicks, and the speed is pretty jumpy as well. Compare this to the spring demo below—it’s night and day:

Fluid motion regardless of interruptions.

Spring-based animation is not necessarily better than tweening in all scenarios—they both have their place. Tweening can be a good solution when you have a set target, a time you want to reach that target by, and there are no interruptions. You get a lot of control over the particular animation, and you can even use a custom curve to get it looking exactly how you like.

Usually tweens that are fast to start and slow to finish feel the most responsive and hide their shortcomings best; e.g. EaseOutCirc.

If your animation needs to respond to interruptions well (most interactive things should), then this is the problem that damped springs solve.

What’s in a Spring?

I’ve modified Ryan Juckett’s iconic Damped Springs code for my spring simulation. His post is a great technical explainer, and I recommend it if you’re a geek.

The layman’s version is that a spring is just a function. You pass in: position, velocity, target position. You get back: position, velocity. How the spring behaves (how quickly your position reaches its target, does it bounce or not, etc) depends on some constant values that are calculated when you initialise the spring.

Not all damped spring implementations are the same, but they usually share similar controls. Here are the parameters that Ryan’s implementation uses to calculate those constants I mentioned:

• Angular Frequency — Controls how fast the spring oscillates (can loosely think of this as speed).
• Damping Ratio — Controls how fast the motion decays.
  • Damping Ratio < 1: Underdamped (some bounce)
  • Damping Ratio == 1: Critically damped (never bounce)
  • Damping Ratio > 1: Overdamped (smooth curve toward target)
• Delta Time — Time between updates—you’re probably familiar, but more on this (much) later. A visual stolen from Apple’s Animate with springs presentation (WWDC23), but reworded to match our definitions.

For this implementation, those human-accessible controls are used to produce 4 coefficients;

Then, we simply use them:

// Perform one "step" of the spring.
private static (float, float) StepSpring(float current, float velocity, float target) {
    float dist = current - target;
    float pos = target + dist * POSPOS_COEF + velocity * POSVEL_COEF;
    float vel = dist * VELPOS_COEF + velocity * VELVEL_COEF;
    return (pos, vel);
}

All we’re doing is calculating a new position and velocity based on distance and those coefficients. There really is no magic going on here.

Spring Transforms

A Spring Transform is just a spring applied to all the components of a transform (position, rotation, scale). The idea is that you have some target transform, for which you set your target position, rotation, scale, and then the actual transform just interpolates towards that using the wonders of spring technology.

Translation and Scale Are Easy

Translation and scale require next-to no modification. Just step the spring over all 3 dimensions:

private static (Vector3, Vector3) StepSpring(Vector3 current, Vector3 velocity, Vector3 target) {  
    Vector3 p;
    Vector3 v;
    (p.x, v.x) = StepSpring(current.x, target.x, oldVel.x, co);
    (p.y, v.y) = StepSpring(current.y, target.y, oldVel.y, co);
    (p.z, v.z) = StepSpring(current.z, target.z, oldVel.z, co);
    return (p, v);
}

Damping Ratio: 0.6, Angular Frequency: 15.0

How the blah does it all connect? Here’s how you might use all that to affect your transform:

// `targetTransform` is just a struct with target values (t,r,s).
Vector3 current = transform.localPosition;
Vector3 target = targetTransform.localPosition;    

(Vector3 newPos, Vector3 newVel) = StepSpring(current, m_velocityPos, target);
transform.localPosition = newPos; // Assign back to our actual transform so that our object moves.
m_velocityPos = newVel;

// Then, repeat for the scale component.
// ...

If you’re hollering at your screen about all the unnecessary copying happening in my StepSpring() functions, put down your lobster and relax. This code is written with the primary goal being ease of understanding.

Rotation Is Tricky

I can’t tell you how much failure I went through trying to apply damped springs to a rotation component. Actually, I can and I will.

The solution I’ve come to is conceptually simple though—all great solutions are—so I feel confident about it.

If you’re here for answers, dammit, then… skip!

The Naive Approach

So, a quaternion in a computer is really just 4 floats. What happens if we just feed those into the spring function? Something pretty good, actually:

Maybe even good enough to use. But there are bugs under the rug—the biggest one being that rotation doesn’t always take the shortest path, so you often get this weird flipping behaviour that looks bad. Once I noticed this, I couldn’t look past it.

We’re also violating quaternions a bit here, evidenced by the fact that we have to re-normalize each step to prevent skewing. This is far from the panacea.

Axis Angles

Another thing we can do is change our representation of rotation velocity to something that’s easier to use with a spring.

The idea is that we replace our velocity with a vector for the axis and an angle. Each iteration, convert the current and target rotations to axis angle representations, and then use the spring on that. A trick here is to encode the angle into the vector’s length, which saves you some bother dealing with positive/negative angles when the axis flips and stuff like that.

In the posts below we end up visualising velocity via axis angle. Here’s how it looks: Dotted orangle line: axis. Orange slice of pizza: angle.

Hopefully that all makes sense conceptually. You have this rotational velocity vector which you calculate and apply each iteration, underpinned by the spring system.

But there’s problems here too. When you move toward the new rotation axis, you’re effectively doing a linear interpolation (as opposed to a spherical linear interpolation), which means the movement is technically incorrect.

It’s best illustrated if you imagine the traditional situation where we want to turn some object to face a different direction. In the following, one arrow represents the direction the object is currently facing, and one represents the direction we want to be facing (it doesn’t matter which is which). Slerp (green) vs Lerp (red)

The red path is much shorter! And insidiously, the speed is inconsistent—we spend much more time at the edges of our path than we do in the middle; These lines intersect with the path at even intervals, I promise.

Our rotation axis is making this same error when we’re stepping our spring towards the new axis. We’re just interpolating from one rotation axis to the next, without care for the spherical nature of it all. But honestly, in spite of all my scaremongering, you can pretty much get away with this. I think you’d struggle to find anyone who’d notice the difference—it’s much harder to see when we’re talking about rotation axes instead of directions, and it only really occurs when a lot of movement is already happening. There’s something wrong with me though, so my search continued.

Unfortunately, I don’t have any code for this approach anymore. Here’s a Stack Overflow answer that outlines one implementation, although it may take a bit of elbow grease to use with the spring system implemented here.

Spherical Coordinates

I also gave spherical coordinates a shot. It sounded sane: convert rotation to a spherical coordinate (these are described by 2 angles and a distance from the origin), do all of the spring calculations in that space, and then finally convert it back and build a rotation out of it. Spherical coordinates, they look like this.

But I imagine all the math guys are tossing their heads back and slapping their knees right now, because it turns out it’s actually quite difficult to get velocity—or really any kind of translation—in spherical coordinates. θ and Φ are essentially longitude and latitude, so if you want to travel across the sphere along a particular path, you need to manage the complicated non-linear relationship between them. If that’s not bad enough, you’ll also need to handle the angles flipping as you cross particular planes:

https://mathinsight.org/spherical_coordinates

There are some papers describing how to work out these sorts of things in spherical coordinates, but it really just felt to me that spherical coordinates are more useful for describe a coordinate, rather than a space to work in and do translations and such.

Maybe I’m missing something with this one, I don’t know. But there should be a simpler answer than this.

Just Use Quaternions

Why don’t we just use quaternions? It makes sense. We have a quaternion for the current orientation, a quaternion for the target orientation, and a velocity quaternion. We just need to fully understand things to get the rotations right.

Now, I hear you: “Quaternions can’t represent rotations larger than 180 degrees! Your velocity quaternion is going to be ruined!” Sure. I saw this discussion a fair bit, and it turned me off using them for a while. But do we really need to be concerned about rotating more than 180 degrees in a single step? With the way our calculations currently work, the velocity variable gets quite large at one of the in-between stages, but we can avoid that, and I’ll show you how.

Here’s how a basic implementation might look for our spring rotation. We do have to write a pretty different StepSpring() function here, so I’ve copied over some commented code from the base implementation to make things easier to follow:

private static Quaternion Multiply(Quaternion input, float scalar) {  
    return new Quaternion(input.x * scalar, input.y * scalar, input.z * scalar, input.w * scalar);  
}

private static Quaternion ShortestRotation(Quaternion a, Quaternion b) {  
    if (Quaternion.Dot(a, b) < 0.0f) {  
        return a * Quaternion.Inverse(Multiply(b, -1.0f));  
    } else {  
        return a * Quaternion.Inverse(b);  
    }  
}

private (Quaternion, Quaternion) StepSpring(Quaternion current, Quaternion velocity, Quaternion target) {
	Quaternion p;
	Quaternion v;

    //float dist = current - target;
    Quaternion fromTo = ShortestRotation(current, target);  // From target to current.
    {
        // dist * POSPOS_COEF
        Quaternion q1 = Quaternion.SlerpUnclamped(Quaternion.identity, fromTo, POSPOS_COEF);  
        // velocity * POSVEL_COEF
        Quaternion q2 = Quaternion.SlerpUnclamped(Quaternion.identity, oldVelocity, POSVEL_COEF);  
        //float pos = target + dist * POSPOS_COEF + velocity * POSVEL_COEF;
        p = q1 * (q2 * target);
    }

    {
        // dist * VELPOS_COEF
        Quaternion q1 = Quaternion.SlerpUnclamped(Quaternion.identity, fromTo, VELPOS_COEF);  
        // velocity * VELVEL_COEF
        Quaternion q2 = Quaternion.SlerpUnclamped(Quaternion.identity, oldVelocity, VELVEL_COEF);  
        // float vel = dist * VELPOS_COEF + velocity * VELVEL_COEF;
        v = q1 * q2;
    }

    return (p, v);
}

You can think of SlerpUnclamped() with an identity rotation as a spherical multiplication. As such, you also don’t need to worry about normalising the result.

Purple - target direction, Green - current direction, Orange - velocity axis and angle. Overdamped spring.

This approach works pretty well until the velocity exceeds 180 degrees, where it gets very confused. It also works for under-damped springs, which I found tricky with an axis-angle approach:

Overcoming Velocity Too Big turns out to just be a matter of looking more closely at the relationship between position and velocity calculations;

float dist = current - target;
// `velocity` here is `vel` from the previous step.
float pos = target + dist * POSPOS_COEF + velocity * POSVEL_COEF;
float vel = dist * VELPOS_COEF + velocity * VELVEL_COEF;

In particular, we notice that velocity always gets multiplied by POSVEL_COEF before being applied, which gives us the actual amount of velocity added to position each step. As you may guess, POSVEL_COEF is really small! New velocity is ultimately derived from dist, so we can effectively pre-apply this multiply by moving it into the velocity calculation instead:

float pos = target + dist * POSPOS_COEF + oldVel;
float vel = dist * VELPOS_COEF * POSVEL_COEF + oldVel * VELVEL_COEF;

Here’s a Desmos graph, if you wanted to play around: https://www.desmos.com/calculator/q6fbtp4yfl.

I always try to be certain I haven’t unintentionally broken something, and in this case it’s easy. Just simulate both versions side by side, and make sure they match:

// Old.
Vector3 current = t.localPosition;
Vector3 target = m_targetTransform.position;

(Vector3 newPos0, Vector3 newVel0) = StepSpringOld(current, m_velocityPos0, target);
(Vector3 newPos1, Vector3 newVel1) = StepSpringNew(currentNew, m_velocityPos1, target);
m_velocityPos0 = newVel0;
m_velocityPos1 = newVel1;

// Returns true if two vectors are approximately equal (https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Vector3-operator_eq.html).
Debug.AssertFormat(newPos0 == newPos1, $"newPos0 does not match newPos1: 0: {newPos0}, 1: {newPos1}.");

// Doesn't really matter which we assign here -- they're the same.
t.localPosition = newPos0; 

Of course, there’s nothing to show here because… nothing happens. The assert doesn’t fire.

Now just straightforwardly copy the concept over to our quaternion step:

private (Quaternion, Quaternion) StepSpring(Quaternion current, Quaternion velocity, Quaternion target) {
    Quaternion p;
    Quaternion v;

    // From target to current.
    Quaternion fromTo = ShortestRotation(current, target);  

    {
        Quaternion q1 = Quaternion.SlerpUnclamped(Quaternion.identity, fromTo, this.posPosCoef);  
        p = q1 * (velocity * target);
    }

    {
        Quaternion q1 = Quaternion.SlerpUnclamped(Quaternion.identity, fromTo, this.velPosCoef * this.posVelCoef);  
        Quaternion q2 = Quaternion.SlerpUnclamped(Quaternion.identity, oldVelocity, this.velVelCoef);  
        v = q1 * q2;
    }

    return (p, v);
}

With velocity a fraction of what it was before, we’re nowhere close to our 180 degree limit, even during fast movement:

Yum.

Of course, it’s not bulletproof. If you have an exceptionally fast rotating spring (> 180 degrees in a single step), you’ll still see issues. But I just don’t think that’s very realistic. Here’s a real fast spring with the angular frequency set to around 300(!), still not breaking that limit:

Fast springs are fine too.

That’s All… ?

So, now that you know how to step all the transform components, you can probably go ahead and make your own pretty good spring transform. So far, I’ve been pretty quiet about how the scaffolding around all this might look, and that’s because ultimately I don’t feel it has much value. The meat of this post is learning about springs, and stepping the components correctly.

I do, however, have some opinionated recommendations.

Here’s my implementation on GitHub if you’d like to take a more complete example: https://github.com/Toqozz/blog-code/blob/master/spring_transforms/Assets/SpringTransform.cs.

Delta Time

Juckett has the following note in his post:

Because simulating damped springs requires calls to potentially expensive trigonometric and exponential functions, I’ve split the process into two steps. The first computes a set of coefficients for the position and velocity parameters by expanding the relevant equations. These coefficients can then be used to quickly update multiple springs using the same angular frequency, damping ratio and time step. If your simulation updates at a locked time step, you can even cache off the coefficients once at initialization time and use them every frame!

Which gives you a few options.

You can run the simulation with a variable delta time by simply re-computing the coefficients with the current delta time before updating your spring. This is going to be slow eventually (hundreds of springs?).

Otherwise, you can run your spring update at a fixed timestep, using your engine’s capabilities or your own; check out the classic Gaffer On Games: Fix your Timestep! post for that.

I’ve also seen a different Update() formula that skips some steps here, but I’m not really sure what the tradeoffs are, so I’m hesitant to recommend it.

 public static void CalcDampedSimpleHarmonicMotion (
    ref float value, 
    ref float velocity, 
    float equilibriumPosition, 
    float deltaTime, 
    float angularFrequency, 
    float dampingRatio)
{
    float x = value - equilibriumPosition;
    velocity += (-dampingRatio * velocity) - (angularFrequency * x);
    value += velocity * deltaTime ;
}

More info: https://gist.github.com/FleshMobProductions/7b523b81d7595e685410be11b24aac3f.

I can see both fixed timestep and variable timestep working well here. Fixed timestep is a bit more effort:

• Make a custom timestep loop.
• Handle interpolation so that things look smooth.

But ultimately more robust:

• Much better performance.
• Deterministic (at least on the same system).
• Immune to frame hitching (without this, you might feasibly break that 180 degree limit).

A variable timestep solution is fine too though. It’s more simple, and that has value.

For implementing a fixed timestep correctly, I once again point you to Gaffer On Games post above, which explains in more detail than I would here. The quick version:

• Accumulate dt every frame.
• Once accumulated time is greater than the fixed timestep, update your things.
• Every frame, run one more temporary step and interpolate towards it depending on how much leftover time there is on the accumulator (float lerpVal = accumulated / stepTime). Next frame, throw that result away and start again from the last solid step.

That last point is obviously the main piece of complexity. You want a system where you can run an additional temporary step, without modifying the data in such a way that you can’t go back to it for the next solid step.

Detecting Rest States

Wouldn’t it be useful if we had some way of telling when the spring had stopped moving? That way, we could easily chain movements together, or execute some code when it reached the target. This sounds trivial, but there’s a couple gotchas I thought I’d mention.

• You need to consider both closeness to target and velocity, to handle under-damped springs.
• In the Quaternion case, just checking equivalency won’t be enough as the same rotation can be represented in more than one way. You want to compare angles, or something more representative of the actual orientation instead.
  • Unity’s standard Quaternion.Angle() may not be accurate enough. You’ll probably want to seek alternatives with more precision.
  • https://discussions.unity.com/t/quaternion-toangleaxis-is-unprecise/248021.
• At the extremes of bouncy or slow moving springs, you may need to get a little creative. The best option here is really to just make the calculation as accurate as possible and expose the resting thresholds to the user (with sensible defaults).
  • Here’s what they do in react-spring, nothing particularly exciting though.
• Once the spring is considered resting, it might be a good idea to assign the current position to the target position, and zero out the velocity.
  • This ensures that both the rest position is perfect, and that the spring is truly resting, regardless of complications in the last point.

Performance

The performance of even a naive implementation is good. If you’re caching coefficients, each spring update is only a few instructions. As we know, updating rotation is significantly more complicated, so that’s where a lot of the time goes.

These results should be taken with lots of salt, as this is version is hardly optimal and also the profiler overhead is likely playing a part: Profile of a naive implementation. 960 springs at ~1.72ms on a Ryzen 9 5900X.

You may notice that there’s a gap—the position/rotation/scale markers don’t add up to 1.72. This ends up being the transform assignment.

If you want more performance, before you go trying to find some crazy optimization for the quaternion lerps, consider a data-oriented approach first. If you’re familiar with Unity, you might be imagining the implementation of a spring transform as a component that you just drop onto a game object. Every frame, Unity will call Update() on all our spring components and they’ll run all their calculations and everything will be fine.

While this is definitely the pattern Unity encourages, having each spring effectively be its own simulation is leaving a lot on the table. Really what you want is some kind of spring manager which iterates over all the springs and updates them in sequence. This way, you can store the data for all those springs in a more data efficient way and take advantage of CPU cache properties, and if you really want to, SIMD instructions.

You can still have a component which you drop onto a game object, but rather than managing and updating itself, have it simply register a spring with some coefficient values with the manager.

We see a >2x speedup (but keep in mind the profiler overhead from before) just by putting things in arrays. These results can be considered accurate—there should be close to zero profiler overhead: Batch implementation. 960 springs at ~0.71ms.

For greater performance, the next step would be to do the work in jobs on other threads, ideally using the burst compiler. I wouldn’t be surprised if you see even a 10x speedup just from the burst compiler—it does good things.

Notes From the Future

2026-06-26

I realised recently that it’s actually quite limiting to have the spring transform as a component itself, which automatically affects the object’s transform.

• It stops you from layering in effects (e.g. one spring for camera movement, another for camera shake).
• It adds complexity with managing world/local spaces. If you just have a spring in an arbitrary space, then the caller decides.
• It makes it harder to batch them together.
• It stops you from simulating to arbitrary points in the future.

The fix is pretty straightforward:

• Stop SpringTransform from inheriting from MonoBehaviour.
• Remove the SetTargetLocal()/SetTargetWorld() etc distinctions. Now it’s just SetTarget().
• Replace Update() with a function Advance(float dt), which simply returns a Frame. The caller can assign it to their transform (or whatever else!) as necessary.

I’m kicking myself for not realising this sooner! Egg on face! I guess that’s what dogfooding is for :)

Resources

• My implementation: https://github.com/Toqozz/blog-code/blob/master/spring_transforms/Assets/SpringTransform.cs
• Juckett’s original article: https://www.ryanjuckett.com/damped-springs/
• Another spring math explainer: https://mathproofs.blogspot.com/2013/07/critically-damped-spring-smoothing.html
• Wrap your head around what the parameters do: https://blog.maximeheckel.com/posts/the-physics-behind-spring-animations/
• Parameter explainer (again): https://www.joshwcomeau.com/animation/a-friendly-introduction-to-spring-physics/

“You didn’t know all this already?” No, I didn’t know all of this already.

Math Notation and Pre/Post-Multiply

There are two main conventions for matrix-vector multiply, and those are pre-multiply and post-multiply.

Post-multiply is the most dominant by far, especially in mathematical texts and really everything other than computer graphics. It represents the vector as a single column matrix on the right side. Like this:

There is also pre-multiply, which represents the vector as a single row matrix on the left side. That looks like this:

You can flip between the two matrix representations by transposing the matrix (reflecting it along its diagonal).

There is no good reasoning for these competing styles. People are just opinionated and one feels better than the other to some. The pre-multiply convention appeared in the DirectX SDK at some point, so that’s probably why it’s more common in graphics. Not necessarily more common than post-multiply, just more common than in other fields.

I’m not too interested in discussing what the actual operations are that happen when you pre-multiply or post-multiply. The core question is: how do we know which is correct in a given situation? The answer to this depends primarily on your math library, and the convention the author preferred. This was pretty surprising to me, but is obvious in hindsight.

In most game math libraries, a Matrix4 type is stored as 4 Vector4 types:

struct Mat4 {
    Vector4 m_elem0;
    Vector4 m_elem1;
    Vector4 m_elem2;
    Vector4 m_elem3;
};

Now, referring back to matrix notations above; does each vector represent a single row, or a single column of the matrix? This is the fundamental difference between libraries. Depending on which is used, it is implied that the translation components live in either the last column (if vectors represent columns) or the last row (if vectors represent rows) of the matrix above, and this is what defines whether you should pre-multiply or post-multiply.

The technical terminology you’ll hear is row vectors if your vectors are rows and column vectors if your vectors are columns.

This detail is obscured by the fact that you’ll often hear it referred to as the library using either column-major or row-major matrices, but row-major and column-major are also computer science terms used to define how 2D arrays are stored in memory, which might lead to you scratching your head on this wikipedia page. This is a decision made by the programming language and totally irrelevant to what we’re talking about here. Our matrices are not even using 2D arrays! When using either convention, the byte storage ends up being identical due to the translation components being flipped, so the storage method really doesn’t tell us anything meaningful here.

Some people might try to tell you that when you hear “row-major” or “column-major” you should think purely of storage and nothing else, but the reality is that much of the world uses this terminology to discriminate between row vectors and column vectors.

Examples

Let’s look at some math libraries and see if we can figure out which convention we should be using.

VectorMath

The aptly named VectorMath is a vector/matrix math library that was open sourced by Sony around 2007. Its matrix class is defined in the following way:

// vectormath.hpp
VECTORMATH_ALIGNED_TYPE_PRE class Matrix4
{
    Vector4 mCol0;
    Vector4 mCol1;
    Vector4 mCol2;
    Vector4 mCol3;
    ...
}

We can easily guess that each element is intended to represent a column in a matrix. But where are the translation components stored?

// matrix.hpp
inline const Vector3 Matrix4::getTranslation() const
{
    return mCol3.getXYZ();
}

Cool, this totally aligns with our column vector math notation above. So we’d expect to use post-multiplication here. Let’s take a look at the operator overloads:

// matrix.hpp
inline const Vector4 Matrix4::operator * (const Vector4 & vec) const
{
    return Vector4(((((mCol0.getX() * vec.getX()) + (mCol1.getX() * vec.getY())) + (mCol2.getX() * vec.getZ())) + (mCol3.getX() * vec.getW())),
                   ((((mCol0.getY() * vec.getX()) + (mCol1.getY() * vec.getY())) + (mCol2.getY() * vec.getZ())) + (mCol3.getY() * vec.getW())),
                   ((((mCol0.getZ() * vec.getX()) + (mCol1.getZ() * vec.getY())) + (mCol2.getZ() * vec.getZ())) + (mCol3.getZ() * vec.getW())),
                   ((((mCol0.getW() * vec.getX()) + (mCol1.getW() * vec.getY())) + (mCol2.getW() * vec.getZ())) + (mCol3.getW() * vec.getW())));
}

// vector.hpp
// <none>

So there’s not even an operator overload for pre-multiplication. The library is clearly telling us that it uses column vectors and post-multiplication, which matches with the standard mathematical notation. If we wanted to be super sure we could also have a proper look at that multiplication operator and make sure that it’s doing what we expect.

This is an example of an opinionated library that really wants there to be a single correct representation for a transformation matrix, and that’s with the translation components in the final column.

zmath

Now let’s take a look at zmath, which is also a SIMD math library for game developers, for the Zig programming language.

Most people aren’t familiar with Zig, so I’ll try to do a bit more explaining here.

// zmath.h
// Fundamental types
pub const F32x4 = @Vector(4, f32);
...

// "Higher-level" aliases
pub const Vec = F32x4;
pub const Mat = [4]F32x4;
pub const Quat = F32x4;

We can see that zmaths matrix type is also backed by an array of 4 F32x4s, which themselves are a group of 4 floats. In Zig, types created with @Vector() are operated on in parallel, using SIMD instructions if possible: https://ziglang.org/documentation/master/#toc-Vectors.

Unlike the Sony library, the fields aren’t named, so we don’t get any clues there. They could represent either rows or columns.

Let’s look at how a translation matrix is created:

pub fn translation(x: f32, y: f32, z: f32) Mat {
    return .{
        f32x4(1.0, 0.0, 0.0, 0.0),
        f32x4(0.0, 1.0, 0.0, 0.0),
        f32x4(0.0, 0.0, 1.0, 0.0),
        f32x4(x, y, z, 1.0),
    };
}

Looks like zmath stores the translation in the final element, just like Sony’s library. But should we use pre or post-multiplication? Let’s have a look at the matrix multiplication:

pub fn mul(a: anytype, b: anytype) mulRetType(@TypeOf(a), @TypeOf(b)) {
    const Ta = @TypeOf(a);
    const Tb = @TypeOf(b);
    // other types stripped ...
    if (Ta == Vec and Tb == Mat) {  // vector vs matrix "overload".
        return vecMulMat(a, b);
    } else if (Ta == Mat and Tb == Vec) {   // matrix vs vector "overload".
        return matMulVec(a, b);
    } else {
        @compileError("zmath.mul() not implemented for types: " ++ @typeName(Ta) ++ ", " ++ @typeName(Tb));
    }
}

This might be a bit Ziggy and hard to follow. Zig doesn’t have operator overloading, but it does have very good type information and compile time abilities. Multiple independent versions of this function will get compiled, according to the types passed in.

Critically, zmath lets us do either pre-multiply or post-multiply. Unfortunately, now we need to look at which version is correct, given that our translation components are in the last element:

fn vecMulMat(v: Vec, m: Mat) Vec {
    var vx = @shuffle(f32, v, undefined, [4]i32{ 0, 0, 0, 0 });
    var vy = @shuffle(f32, v, undefined, [4]i32{ 1, 1, 1, 1 });
    var vz = @shuffle(f32, v, undefined, [4]i32{ 2, 2, 2, 2 });
    var vw = @shuffle(f32, v, undefined, [4]i32{ 3, 3, 3, 3 });
    return vx * m[0] + vy * m[1] + vz * m[2] + vw * m[3];
}
fn matMulVec(m: Mat, v: Vec) Vec {
    return .{ dot4(m[0], v)[0], dot4(m[1], v)[0], dot4(m[2], v)[0], dot4(m[3], v)[0] };
}

If you’re like me, you won’t intuitively know which of these is right, and you’ll just need to do it the hard way by manually verifying, or writing some test code:

const translation = zm.translation(0.0, 99.0, 0.0);
const point = zm.f32x4(0.0, 0.0, 0.0, 1.0);
const post_mult = zm.mul(translation, point);
const pre_mult = zm.mul(point, translation);
std.debug.print("post_mult: {any}\npre_mult: {any}\n", .{ post_mult, pre_mult });

$ ./out
post_mult: { 0.0, 0.0, 0.0, 1.0 }
pre_mult: { 0.0, 99.0, 0.0, 1.0 }

Ok, so post-multiplication did nothing and pre-multiplication produced the correct result, so zmath must use row vectors. What if we manually make a matrix and store translation at the end of each element instead?

// Translation stored on the "right" instead of the "bottom".
const translation = zm.Mat{
    zm.f32x4(1.0, 0.0, 0.0, 0.0),
    zm.f32x4(0.0, 1.0, 0.0, 99.0),
    zm.f32x4(0.0, 0.0, 1.0, 0.0),
    zm.f32x4(0.0, 0.0, 0.0, 1.0),
};
const point = zm.f32x4(0.0, 0.0, 0.0, 1.0);
const post_mult = zm.mul(translation, point);
const pre_mult = zm.mul(point, translation);

$ ./out
post_mult: { 0.0, 99.0, 0.0, 1.0 }
pre_mult: { 0.0, 0.0, 0.0, 1.0 }

Now post-multiplication is correct. So I guess this is just zmath supporting both row and column vectors and letting the user decide, even though post-multiplication won’t work with a matrix created via zm.translation().

I’m not a fan of this kind of implementation, especially given that this library is advertised as a library for game developers.

Shader languages also commonly let you multiply things in any order, which is also a source of confusion. If you upload your zmath matrices to the GPU and run your WGSL shader on them, you’ll have to flip to using post-multiplication instead, unless you transpose your matrices before upload. This is because WGSL treats matrices as column vectors:

A matrix is a grouped sequence of 2, 3, or 4 floating point vectors. The key use case for a matrix is to embody a linear transformation. In this interpretation, the vectors of a matrix are treated as column vectors.

The fact that you could have a shader that uses pre-multiply for some matrices and post-multiply for others is wild to me, but ultimately make sense.

So there you have it. Two libraries using identical memory representations but different conventions around multiplying matrices. All that matters is what the math library actually does. In hindsight it’s obvious.

What about matrix multiplication order?

One good thing is that once you’ve figured out pre or post-multiply, the rules are the same for matrices, unless you’re using the math library of a madman…

If using pre-multiplication (row vectors), then matrices should be combined left-to-right:

// A matrix that takes you from local to world space, then from world space to clip space.
Matrix object_to_clip = object_to_world * world_to_clip;
Vector4 result = local_pos * object_to_clip;

If using post-multiplication (column vectors), then matrices should be combined right-to-left:

// A matrix that takes you from local to world space, then from world space to clip space.
Matrix object_to_clip = world_to_clip * object_to_world;
Vector4 result = object_to_clip * local_pos;

One More Example

To make things abundantly clear, here’s how a typical vertex shader in GLSL (which uses column vectors – post-multiplication) would calculate gl_Position, given raw matrices from VectorMath that have not been transposed:

layout(location = 0) in vec3 inPosition;
uniform mat4 objectMatrix;
uniform mat4 projectionMatrix;

void main()
{
    gl_Position = projectionMatrix * objectMatrix * vec4(inPosition, 1.0);
}

And here’s what it would look like if you uploaded the raw matrices from zmath without transposition:

layout(location = 0) in vec3 inPosition;
uniform mat4 objectMatrix;
uniform mat4 projectionMatrix;

void main()
{
    gl_Position = projectionMatrix * objectMatrix * vec4(inPosition, 1.0);
}

They’re the same! Of course they are – the underlying memory representation is the same in both libraries. The difference is that we’re switching to GLSL’s math library, which uses column vectors, and interprets our matrices as columns of vectors.

If this all makes sense to you then you probably understand the concept enough to never be bothered by it again.

Useful Links/Resources

• A catalogue of the differences between shading languages, including information about their matrix representations: https://gist.github.com/teoxoy/936891c16c2a3d1c3c5e7204ac6cd76c#21-storage-address-space
• Another good explanation on the Khronos forums: https://community.khronos.org/t/row-major-vs-column-major-in-4-1/64122
• Matrix multiply confusion, and an OpenGL author dispelling it: https://steve.hollasch.net/cgindex/math/matrix/column-vec.html
• A more detailed explainer that goes into the math, as well as coordinate spaces: https://seanmiddleditch.github.io/matrices-handedness-pre-and-post-multiplication-row-vs-column-major-and-notations/
• Another explainer: https://austinmorlan.com/posts/opengl_matrices/
• Pretty useful overal resource on OpenGL transformations: https://www.opengl.org/archives/resources/faq/technical/transformations.htm

A recording of a recording.

Recently I was struggling to record some demo webms on macOS – basic stuff, like moving a sprite back and forth with some logic. For some reason, I couldn’t get things to move smoothly, without stuttering, so all my recordings were messed up. This issue itself is bizarre (this should be possible, and trust me, I tried), but that’s not the point of this post. In reality, you’re never going to get a truly high quality recording from a screen capture anyway. Games are constantly fighting the OS for processor time, and even well-made games have frame timing issues. If you’re not pumping out a new frame exactly every 16.6667ms (or whatever your desired framerate is), then your recording is flawed.

The proper solution for recording video is to run your game with a fixed delta time (whatever you want your video framerate to be recorded at) and just spit out images from the game every frame, and then compile those into a video. You’ll get a perfectly smooth recording of your game, regardless of framerate issues.

This is actually how a lot of recording works for video game frag movies. Lawena is a tool for source engine games which lets you crank the graphics settings of your game and record at any framerate you want. It’s really important when you’re compiling a video like that to have high quality source recordings, sometimes at over 240FPS (for slow-mo effects).

Additionally, when you record directly from the frame buffer, you have control over when in the frame your recording should take place. For example, if you wanted to do some custom post processing, you could copy your frame before post processing passes are applied.

Why is my recording flawed if my framerate is slightly off? Here’s a comparison of game frames (white), to recording frames (red diamonds). Assuming the recording can keep up, when you’re recording your screen, you can assume that the recording program is capturing a frame at every interval (60FPS – ~16.67ms in this case). Remember that when the recorder captures a frame, it’s actually capturing the last displayed frame, which could have been who knows how long ago (the dotted red lines at the top signify how much time we’re missing at each recording sample). The result of this is that if you were to step through the frames in your video file, you’d trivially notice that each frame doesn’t have the same amount of movement, despite the recording being at a constant framerate.

I’ve also seen people, when trying to make recordings where the game won’t make framerate, slow the game down to half speed, do the recording, and then speed it up 2x in editing software so that things look smooth. This is obviously flawed if you understand the above. Please don’t do this. If you absolutely must, then record in the highest framerate you possibly can so that the ‘lost time’ is minimized.

The Naive Solution

The naive solution is obvious. All you really need is a way to grab the output pixels from the framebuffer, and write those pixels to some kind of image format. From there you can use other tools like ffmpeg to compile the frames into video.

Accessing the framebuffer is not always easy if a suitable abstraction is not provided, but most major engines should have something. I’ve been meaning to try out wgpu some more, so I just built something from those primitives. Here’s the basics of how I’m grabbing the output frame pixels and dumping them to a .png, for those curious:

// `end_frame` is a function on a `Recorder` struct which keeps track of recording state etc.
pub fn end_frame(&mut self, device: &wgpu::Device, encoder: &mut wgpu::CommandEncoder, frame_texture: &wgpu::Texture) {
    if !self.recording {
        return;
    }

    // Copy our screen tetxure data into a buffer.
    encoder.copy_texture_to_buffer(
        wgpu::ImageCopyTexture {
            aspect: wgpu::TextureAspect::All,
            texture: frame_texture,
            mip_level: 0,
            origin: wgpu::Origin3d::ZERO,
        },
        wgpu::ImageCopyBuffer {
            buffer: &self.buffer,
            layout: wgpu::ImageDataLayout {
                offset: 0,
                bytes_per_row: Some(4 * self.width),    // 4 bytes (bgra) * width
                rows_per_image: Some(self.height),
            },
        },
        frame_texture.size(),
    );

    // Map the buffer so that we can read it on the CPU side.
    // It's an async operation in wgpu, so just block for simplicity.
    let buffer_slice = self.buffer.slice(..);
    pollster::block_on(async {
        let (tx, rx) = futures_intrusive::channel::shared::oneshot_channel();
        buffer_slice.map_async(wgpu::MapMode::Read, move |result| {
            tx.send(result).unwrap();
        });

        device.poll(wgpu::Maintain::Wait);
        rx.receive().await.unwrap().unwrap();
    });

    // Finally write out our png.
    {
        let filename = format!("frame_{:06}.png", self.frame_number);
        self.frame_number += 1;
        // `data` gets dropped at the end of this scope, so that we can unmap the buffer.
        let data = buffer_slice.get_mapped_range();
        lodepng::encode_file(
            &filename,
            &data,
            self.width as usize,
            self.height as usize,
            lodepng::ColorType::BGRA,
            8,
        ).expect("Failed to write PNG.");
    }

    self.buffer.unmap();
}

It looks like Unity has the ScreenCapture class for getting pixels, though I suspect there’s better ways.

You’ll also want to artificially set your game’s dt to whatever the recording framerate is, so that your game appears to be running at that framerate in the recording:

pub fn update(&mut self, real_dt: f32) {
    let dt = {
        if self.recorder.is_recording() {
            1.0 / self.recorder.recording_framerate() as f32
        } else {
            real_dt
        }
    };

    ...
}

You should also consider limiting the game’s framerate to match this so that it’s actually playable, but note that framerate limiting should not generally be considered a substitute for setting the dt if you want a perfect recording.

When you’re done, you can use ffmpeg to compile the PNGs into whatever format you want:

ffmpeg -framerate 60 -i frame_%06d.png -c:v libx264 -profile:v high -crf 20 -pix_fmt yuv420p output.mp4

This behaves fine, but leaves a lot to be desired. The first issue is that writing PNGs is slow. It took me 24ms~ on average to write a PNG to disk in a release build, and debug builds are much slower. This alone is enough to stop us from recording and playing at the same time at 60FPS (although the recording itself will still look smooth for reasons that should be clear by now). The second issue is that this approach quickly eats drive space for longer recordings, especially with complex scenes where PNG’s compression isn’t doing as much.

Profile capture taken with Tracy Profiler.

lodepng is not the best we can do. There are faster PNG encoders. We could also turn down the compression for a faster write, or use a different format altogether.

If you’re wondering how much of this time is the OS writing the file to disk: it’s about a millisecond faster on average when we encode into memory.

Encoding With ffmpeg Directly

It turns out that ffmpeg actually accepts raw frames (of course). So you can simplify this whole pipeline by just sending the raw data to ffmpeg directly and letting it handle it. Here’s roughly the process I’m using:

• When recording starts:
  • Launch an ffmpeg process in a separate thread. Spin in that thread, writing all the received frames into the process’ stdin.
  • Enable ‘recording mode’, which sets the game’s dt to 1.0/60.0 (my target recording framerate) and limits the game’s framerate so that things are playable.
• At the end of every frame, grab the frame output and send the raw bytes through to the ffmpeg thread. You’ll want to buffer (i.e. copy) the output here, since ffmpeg might take longer than a frame to encode your video frame.
• When recording stops:
  • Close stdin on the ffmpeg thread and .join() from the main thread (this is blocking until ffmpeg finishes writing the file).
  • Disable recording mode.

The ffmpeg command you’ll want for raw frames is something like the following:

ffmpeg
    -r 60               # your framerate
    -f rawvideo
    -vcodec rawvideo
    -pix_fmt bgra       # your pixel format
    -s 1280x720         # your window size
    -i -                # input as stdin
    -c:v libvpx-vp9     # standard webm codec
    -pix_fmt yuv420p    # standard pixel format
    output.webm

There’s really not much to it. In fact, it almost doesn’t feel like it’s worth writing about. But before I got this working I didn’t really have a concrete idea about how this all should work, so I figured it’s worth sharing.

You’ll notice that I’m sidestepping my ‘first’ issue with writing the PNGs: encoding with ffmpeg is also slow, and we can’t do it on the main thread. You could also encode your PNGs in a separate thread to the same effect, or just use a format that’s faster to encode. I mostly just wanted to complain and show off the Tracy Profiler. I guess I’m also more OK with accepting a separate thread for handling the whole recording/encoding pipeline, rather than just for writing out a buffer of images.

Here’s some code for how I’m doing my recordings. The main thing I’m yet to do is wait for the ffmpeg process to finish in a non-blocking way, and display the progress (displaying the frames waiting for encoding would be enough). This code is truncated to make it easier to read for the purposes of the post; you can find the full source on Github.

// recorder.rs
pub fn begin_record(&mut self) {
    self.recording = true;       

    assert!(self.ffmpeg.is_none());
    let ffmpeg = {
        let (send, recv) = mpsc::channel::<Vec<u8>>();
        let (width, height) = (self.width, self.height);
        let handle = thread::spawn(move || {
            // do ffmpeg stuff
            let size = format!("{}x{}", width, height);
            let ffmpeg_cmd = "ffmpeg";
            let args = [
                "-r", "60",                     // Input frame rate.
                "-f", "rawvideo",               // Input format.
                "-vcodec", "rawvideo",
                "-pix_fmt", "bgra",
                "-s", &size,
                "-i", "-",                      // Input as stdin.
                "-c:v", "libvpx-vp9",           // Output codec.
                "-pix_fmt", "yuv420p",
                "-y",                           // Overwrite output file.
                "output.webm",                  // File name.
            ];

            let mut child = std::process::Command::new(ffmpeg_cmd)
                .args(&args)
                .stdin(Stdio::piped())
                .spawn()
                .expect("Failed to spawn FFmpeg command");
            
            let stdin = child.stdin.as_mut().expect("Couldn't open ffmpeg stdin.");
            
            for data in recv {
                stdin.write_all(data.as_slice()).unwrap();
            }
            
            let output = child.wait_with_output().unwrap();
            // Check the output and error messages
            if output.status.success() {
                println!("FFmpeg command executed successfully.");
            } else {
                // The `stderr` field of the output contains any error messages
                let error_message = String::from_utf8_lossy(&output.stderr);
                println!("FFmpeg command failed: {}", error_message);
            }
        });
        
        FfmpegProcess {
            send,
            handle,
        }
    };
    
    self.ffmpeg = Some(ffmpeg);
}

pub fn end_frame(
    &mut self,
    device: &wgpu::Device,
    encoder: &mut wgpu::CommandEncoder,
    frame_texture: &wgpu::Texture
) {
    if !self.recording {
        return;
    }

    encoder.copy_texture_to_buffer(
        wgpu::ImageCopyTexture {
            aspect: wgpu::TextureAspect::All,
            texture: frame_texture,
            mip_level: 0,
            origin: wgpu::Origin3d::ZERO,
        },
        wgpu::ImageCopyBuffer {
            buffer: &self.buffer,
            layout: wgpu::ImageDataLayout {
                offset: 0,
                bytes_per_row: Some(4 * self.width),    // 4 bytes (bgra) * width
                rows_per_image: Some(self.height),
            },
        },
        frame_texture.size(),
    );

    let buffer_slice = self.buffer.slice(..);
    pollster::block_on(async {
        let (tx, rx) = futures_intrusive::channel::shared::oneshot_channel();
        buffer_slice.map_async(wgpu::MapMode::Read, move |result| {
            tx.send(result).unwrap();
        });
        device.poll(wgpu::Maintain::Wait);
        rx.receive().await.unwrap().unwrap();
    });
            
    {
        // We need to drop this before unmapping.
        let data = buffer_slice.get_mapped_range();

        // Send buffer to recording thread.  We need to copy the data to do this safely.
        if self.recording {
            let ffmpeg = self.ffmpeg.as_mut().unwrap();
            let mut vec = Vec::with_capacity(data.len());
            vec.extend_from_slice(&data);
            ffmpeg.send.send(v).expect("Failed to send to ffmpeg thread.");
        }
    }

    self.buffer.unmap();
}

pub fn end_record(&mut self) {
    self.recording = false;
    
    let ffmpeg = self.ffmpeg.take().unwrap();
    drop(ffmpeg.send);
    ffmpeg.handle.join().unwrap();
}

Lessons Learned From The Future

13/02/2025

There are a few more noteworthy things that I’ve come across using this in a non-indie environment.

Pipe Behaviour

Pipes are inherently quite tied to the OS. In implementing this through C with Windows APIs you might learn that there’s actually a lot of OS-specific setup and choices to make, in contrast to the Rust standard library, which is more-or-less “give me a pipe”.

You can of course configure the pipe however you like with Rust, these details are just abstracted away by default.

Check out the pipe setup in this project on GitHub for a sensible Windows/C++ implementation.

The kinds of choices here are unsurprisingly about the specifics of I/O. Typically the encoding process is slower than the recording – the game may be pumping out 60fps, while your encoder can only encode 30fps. This time needs to be reclaimed at some point, and you’ll want to consider your tradeoffs here. On Windows, a non-async pipe will block on write once it’s backed up enough, which is fine for recording pre-made scenes, but not so much if you’re trying to interact or play – lots of stuttering. Of course, this stuttering won’t be present in the recording, just while playing.

The easiest solution is to just pick a fast encoder (such as NVENC) when recording interactive shots.

Media Players Like YUV420

Although the command in my original post actually has this already, I think it’s worth drawing more attention to. -pix_fmt yuv420p is important if you want your video to just work on the most possible video players. It tells ffmpeg to encode the video in the YUV colour space, with 4:2:0 subsampling. Without this flag, much of the time ffmpeg will default to -pix_fmt yuv444p, which is 4:4:4 subsampling. Advanced video players such as mpv and vlc will generally play either back just fine, but more primitive ones will not (Windows Media Player, some web browsers, etc).

FFmpeg Syntax

This isn’t really a problem, but I ended up moving towards the following command syntax which I like more:

ffmpeg -y -f rawvideo -framerate 60 -pix_fmt rgba -s:v 1920x1080 -i pipe:0 -c:v libx264 -pix_fmt yuv420p -crf 26 -preset ultrafast output.mp4

Some of these actually do have consequences. -s:v will change specifically the video stream’s resolution, while -s usually affects the video stream by default. It’s all pretty confusing.

For the past month and a bit I’ve been working on a (2D) game which uses a rope as a core mechanic. I expected this to be challenging, but was (unsurprisingly) caught by a bunch of things and learnt some valuable lessons along the way, which I’m hoping to document here.

Let’s first acknowledge that rope is used pretty sparingly in video games, with good reason:

• It’s computationally expensive to simulate.
• It’s cognitively expensive to develop.
• Using physically-based rope for anything remotely interesting is full of edge cases and other hurdles.
• It can be a pain to render.

It also might just be not that exciting as a game mechanic, but we can’t work that out without solving the technical problems first.

This isn’t to say you can’t implement a rope that looks good and works fine. Actually, if you’re willing to make some concessions, believable rope is damn easy. It’s really only once the rope becomes a meaningful mechanic, and utilises things like collision, that things get a bit hairy. Hopefully I can help to solve some of these for you.

This post is largely about working in 2D, but most concepts should be able to be transferred to 3D as well. Likewise, code in this post is Unity-specific, but should be able to be adjusted to fit any language or engine.

Write Your Own Physics

Don’t make the mistake of seeing “hinge joint”, “angle joint”, or some other variation in your game/physics engine and thinking you can string a bunch of them together to make a rope. Not only will it be buggy, but you’ll have to do a lot more work to have any control over it, and any new interaction you want to code will be anxiety in a bottle.

Verlet integration–specifically position-based Verlet–is a very easy to understand method for calculating trajectories of objects, used as an alternative to something like Euler or RK4 integration. Verlet in general is used often in molecular dynamics for its high stability, but that’s not really what we’re interested in. Position-based Verlet is a great fit for simulating rope because it calculates the velocity of an object from its previous position:

const float STEP_TIME = .01f;
Vector2 gravity = new Vector2(0f, -9.8f);

// Euler (semi-implicit) approach:
// The RK4 struct would be very similar if not identical.
class EulerObject {
    public Vector2 position;
    public Vector2 velocity;
    public float mass;
}

void StepEuler(EulerObject obj) {
    // Euler (semi-implicit) calculation:
    // acceleration = force / mass;
    // next_vel = vel + (acceleration * dt);
    // next_pos = cur_pos + (next_vel * dt);
    Vector2 acceleration = gravity / obj.mass;
    obj.velocity += acceleration * stepTime;
    obj.position += velocity * stepTime;
}

// Verlet approach:
class VerletNode {
    public Vector2 position;
    public Vector2 oldPosition;
}

void StepVerlet(VerletNode node) {
    // Verlet calculation (velocity derived from previous step):
    // next_pos = cur_pos + (cur_pos - old_pos) + acceleration * dt * dt;
    // NOTE: cur_pos - old_pos is not actual velocity.  To calculate real velocity, use (cur_pos - old_pos) / dt.
    Vector2 temp = node.position;
    node.position += (node.position - node.oldPosition) + gravity * STEP_TIME * STEP_TIME;
    node.oldPosition = temp;
}

Why the names EulerObject and VerletNode? In your typical (Euler-based) physics engine, you expect each physical object to have some kind of Rigidbody concept, with a position, velocity, mass, etc, and a collider. In a Verlet-based simulation, you’re much more likely to see the integration properties (position, velocity, etc) attached to the actual vertices of the collider, if a collider is being used at all.

The implication this has is that we don’t need to do any velocity calculation ourselves to have a good looking simulation, we just need to update object positions. A good example of this behavior being useful might be to imagine an object which is programmed to follow the mouse cursor. With a position-based integrator, we can flick the mouse, release the object, and expect it to fly naturally on its own. Normally, we’d be expected to do some release velocity calculation, and then manually add the appropriate force to the Rigidbody.

Verlet demo (smoothing applied).

The last piece of the puzzle here is distance constraints, which aim to keep the distance between two nodes constant ^obviously. After applying velocity, we move the position of each node in the rope to a new one which obeys the distance constraint. This is an iterative process, and it doesn’t ensure that constraints are satisfied after it’s finished; we apply the constraints many times to get reasonably close to a solve–when I mention “iterations” throughout this post, this is what I’m referring to. Again, position-based integration makes this easier because we only need to update positions and let the simulation figure things out with the new information.

If you put all that together you’ll get something like the following:

public class VerletNode {
    public Vector2 position;
    public Vector2 oldPosition;
    
    public VerletNode(Vector2 startPos) {
        this.position = startPos;
        this.oldPosition = startPos;
    }
}

public class Rope : MonoBehaviour {
    public int iterations = 80;

    public int totalNodes = 40;
    public float nodeDistance = .1f;
    public Vector2 gravity;	// (0f, -20f)

    private VerletNode[] nodes;

    private void Awake() {
        nodes = new VerletNode[totalNodes];

        // Spawn nodes starting from the transform position and working down.
        Vector2 pos = transform.position;
        for (int i = 0; i < totalNodes; i++) {
            nodes[i] = new VerletNode(pos);
            pos.y -= nodeDistance;
        }
    }

    private void FixedUpdate() {
        Simulate();
        for (int i = 0; i < iterations; i++) {
            ApplyConstraints();
        }
    }

    private void Simulate() {
        for (int i = 0; i < nodes.Length; i++) {
            VerletNode node = nodes[i];

            Vector2 temp = node.position;
            node.position += (node.position - node.oldPosition) + gravity * (Time.fixedDeltaTime * Time.fixedDeltaTime);
            node.oldPosition = temp;
        }
    }

    private void ApplyConstraints() {  
        for (int i = 0; i < nodes.Length - 1; i++) {
            VerletNode node1 = nodes[i];
            VerletNode node2 = nodes[i + 1];

            // First node follows the mouse, for debugging.
            if (i == 0 && Input.GetMouseButton(0)) {
                // Camera.main is terribly inefficient here, you should cache the camera.
                node1.position = cam.ScreenToWorldPoint(Input.mousePosition);
            }

            // Current distance between rope nodes.
            float diffX = node1.position.x - node2.position.x;
            float diffY = node1.position.y - node2.position.y;
            float dist = Vector2.Distance(node1.position, node2.position);
            float difference = 0;
            // Guard against divide by 0.
            if (dist > 0) { 
                difference = (nodeDistance - dist) / dist;
            }

            Vector2 translate = new Vector2(diffX, diffY) * (.5f * difference);

            node1.position += translate;
            node2.position -= translate;
        }
    }
}

View the complete script on GitHub here (contains work discussed later).

That might seem like a lot to digest, but we’ve covered most of the theory. There are a few bonus things I would like to mention though:

Use Fixed Timestep

If for some bad reason you’re like me and are considering a variable delta time for your physics, the TL;DR is don’t. There are ways to simulate Verlet integration with a variable delta time, but you’ll never get the consistency of a fixed timestep, and the lack of predictable behavior is just crippling.

The GitHub version uses a custom fixed timestep implementation which can offer some more flexibility here.

Number of Iterations

The more iterations you have, the stiffer the rope will be. The more nodes you have, the more iterations you need to maintain that stiffness. So things get pretty slow if you want a long and detailed rope. If you’re in Unity and your rope is super long, you probably want to look at the Burst compiler, discussed later.

There’s also a good optimization to reduce iterations by adding an additional constraint between the first and the last node, making sure that the overall rope length stays consistent, and lessening the load for the other constraints. There is a downside of the rope feeling a bit weird when stretched, so try both to see whether this is worthwhile for you:

// Distance constraint which reduces iterations, but doesn't handle stretchyness in a natural way.
VerletNode first = nodes[0];
VerletNode last = nodes[nodes.Length-1];
// Same distance calculation as above, but less optimal.
float distance = Vector2.Distance(first.position, last.position);
if (distance > 0 && distance > nodes.Length * nodeDistance) {
    Vector2 dir = (last.position - first.position).normalized;
    last.position = first.position + nodes.Length * nodeDistance * dir;
}

Debug Rendering

Debug rendering is as easy as drawing lines between the points. Here’s a gizmos implementation:

private void OnDrawGizmos() {
    if (!Application.isPlaying) {
        return;
    }

    for (int i = 0; i < nodes.Length - 1; i++) {
        if (i % 2 == 0) {
            Gizmos.color = Color.green;
        } else {
            Gizmos.color = Color.white;
        }

        Gizmos.DrawLine(nodes[i].position, nodes[i+1].position);
    }
}

This makes for a pretty good (and fun to play with) rope simulation! But it’s missing collision, which makes it difficult to utilize the rope mechanically.

Collision Detection and Resolution

Unfortunately, collision, and more specifically collision resolution, is really the hard part of physics simulations. Our Verlet sim makes things a bit easier, but some of the stuff is still alien. I’ll be walking us through collision resolution for the 2 most basic colliders, Circle and Box.

The basic idea is that we should check collisions each time we move a node, and if the node is colliding after the move then we should resolve the collision by pushing it out the shortest distance we can. This includes movement via constraints, so we need to check collision of each node every iteration.

Rope swings into collider, and nodes are pushed out along the closest edge.

For relatively detailed and stiff rope (40 nodes, 80 iterations), that’s potentially 3,200 collision resolves each tick, more if nodes are touching multiple colliders at once. We’ll need something fast here.

Detection

The easiest way for us to detect rope collision is to use an overlap circle around each node, which will return an array of colliders within the specified radius of said node. I mentioned before that we need to detect collision every iteration. The thing is that collision objects don’t actually move between iterations because our rope simulation all happens in a single frame, and so it doesn’t make sense to query the physics engine every iteration. What we actually want to do is take a kind of snapshot of the colliders within a reasonable distance of the rope, and use that for our entire rope step.

In Unity (and in most physics engines), colliders only update each physics tick, even if their transform moved in-between. This means we only have to update the snapshot of the latest physics steps. This is important if you’re using a custom step time for your rope.

“Snapshot” colliders within a reasonable distance of the rope.

Here’s an excerpt of our rope script with the snapshot implementation:

enum ColliderType {
    Circle,
    Box,
    None,
}

class CollisionInfo {
    public int id;

    public ColliderType colliderType;
    public Vector2 colliderSize;
    public Vector2 position;
    public Vector2 scale;
    public Matrix4x4 wtl;
    public Matrix4x4 ltw;
    public int numCollisions;
    public int[] collidingNodes; // You probably want to use byte[] here instead, unless you have >255 nodes.

    public CollisionInfo(int maxCollisions) {
        this.id = -1;
        this.colliderType = ColliderType.None;
        this.colliderSize = Vector2.zero;
        this.position = Vector2.zero;
        this.scale = Vector2.zero;
        this.wtl = Matrix4x4.zero;
        this.ltw = Matrix4x4.zero;

        this.numCollisions = 0;
        this.collidingNodes = new int[maxCollisions];
    }
}

public class Rope : MonoBehaviour {
    // Maximum total number of colliders that the rope can touch.
    private const int MAX_ROPE_COLLISIONS = 32;
    // Collision radius around each node.  Set it high to avoid tunneling.
    private const int COLLISION_RADIUS = .5f;
    // Collider buffer size; the maximum number of colliders that a single node can touch at once.
    private const int COLLIDER_BUFFER_SIZE = 8;

    public int totalNodes;
    // -- *snip* --
    public float collisionRadius = .5f; // Snapshot radius around each node, set it high to avoid tunneling.
    private int numCollisions;
    private bool shouldSnapshotCollision;
	private CollisionInfo[] collisionInfos;
    private Collider2D[] colliderBuffer;
    
    private void Awake() {
        // -- *snip* --
        // Allocate collision structures.
        collisionInfos = new CollisionInfo[MAX_ROPE_COLLISIONS];
        for (int i = 0; i < collisionInfos.Length; i++) {
            // Each collider can collide with as many nodes as are in the rope.
            collisionInfos[i] = new CollisionInfo(totalNodes);
        }

        // Buffer for `OverlapCircleNonAlloc`.
        colliderBuffer = new Collider2D[COLLIDER_BUFFER_SIZE];
    }

    private void FixedUpdate() {
        shouldSnapshotCollision = true;
    }

    private int SnapshotCollisions() {
        numCollisions = 0;
        // Loop through each node and get collisions within a radius.
        for (int i = 0; i < nodes.Length; i++) {
            int collisions =
                Physics2D.OverlapCircleNonAlloc(nodes[i].position, collisionRadius, colliderBuffer);

            for (int j = 0; j < collisions; j++) {
                Collider2D col = colliderBuffer[j];
                int id = col.GetInstanceID();

                // Check if we already have this collider in our collisionInfos.
                int idx = -1;
                for (int k = 0; k < numCollisions; k++) {
                    if (collisionInfos[k].id == id) {
                        idx = k;
                        break;
                    }
                }

                // If we didn't have the collider, we need to add it.
                if (idx < 0) {
                    // Record all the data we need to use into our class.
                    CollisionInfo ci = collisionInfos[numCollisions];
                    ci.id = id;
                    ci.wtl = col.transform.worldToLocalMatrix;
                    ci.ltw = col.transform.localToWorldMatrix;
                    ci.scale.x = ci.ltw.GetColumn(0).magnitude;
                    ci.scale.y = ci.ltw.GetColumn(1).magnitude;
                    ci.position = col.transform.position;
                    ci.numCollisions = 1;	// 1 collision, this one.
                    ci.collidingNodes[0] = i;

                    switch (col) {
                        case CircleCollider2D c:
                            ci.colliderType = ColliderType.Circle;
                            ci.colliderSize.x = ci.colliderSize.y = c.radius;
                            break;
                        case BoxCollider2D b:
                            ci.colliderType = ColliderType.Box;
                            ci.colliderSize = b.size;
                            break;
                        default:
                            ci.colliderType = ColliderType.None;
                            break;
                    }

                    numCollisions++;
                    if (numCollisions >= MAX_ROPE_COLLISIONS) {
                        return;
                    }
                // If we found the collider, then we just have to increment collisions and add our node.
                } else {
                    CollisionInfo ci = collisionInfos[idx];
                    if (ci.numCollisions >= totalNodes) {
                        continue;
                    }

                    ci.collidingNodes[ci.numCollisions++] = i;
                }
            }
        }

        shouldSnapshotCollision = false;
    }
}

I apologise for the volume of code in this post; this shit is technical!

The first thing to notice is that the CollisionInfo class, which we use to hold the data we need from Collider2D. Using a reference to the Collider2D is much slower (~2x), probably due to its large size and scattered pointers, both of which are terrible for cache performance.

There’s an annoying amount of constants. Feel free to convert the arrays to lists to avoid some of these, I just prefer having control over the allocations.

An unexpected complication is that we have to do a bit of work to check whether we already have each collider before adding it. If you’re expecting many collisions (more than 30), you probably want to consider a Dictionary or some kind of Set to store the collision information. If you’re not expecting so many, a dictionary will likely just make things slower.

Resolution

Circle collisions are easily resolved by checking the node distance against the collider radius. Collisions with boxes that rotate, however, can be challenging. The easiest way is to convert our collision point to the box’s local space, which removes the scale and rotation, making it axis-aligned, which is considerably easier to work with. Once we’ve detected and resolved the collision, we can convert the no-longer-colliding point back to world space.

private void AdjustCollisions() {
    for (int i = 0; i < numCollisions; i++) {
        CollisionInfo ci = collisionInfos[i];

        switch (ci.colliderType) {
            case ColliderType.Circle: {
                float radius = ci.colliderSize.x * Mathf.Max(ci.scale.x, ci.scale.y);

                for (int j = 0; j < ci.numCollisions; j++) {
                    VerletNode node = nodes[ci.collidingNodes[j]];
                    float distance = Vector2.Distance(ci.position, node.position);

                    // Early out if we're not colliding.
                    if (distance - radius > 0) {
                        continue;
                    }

                    // Push point outside circle.
                    Vector2 dir = (node.position - ci.position).normalized;
                    Vector2 hitPos = ci.position + dir * radius;
                    node.position = hitPos;
                }
            } break;

            case ColliderType.Box: {
                for (int j = 0; j < ci.numCollisions; j++) {
                    VerletNode node = nodes[ci.collidingNodes[j]];
                    Vector2 localPoint = ci.wtl.MultiplyPoint(node.position);

                    // If distance from center is more than box "radius", then we can't be colliding.
                    Vector2 half = ci.colliderSize * .5f;
                    Vector2 scalar = ci.scale;
                    float dx = localPoint.x;
                    float px = half.x - Mathf.Abs(dx);
                    if (px <= 0) {
                        continue;
                    }

                    float dy = localPoint.y;
                    float py = half.y - Mathf.Abs(dy);
                    if (py <= 0) {
                        continue;
                    }

                    // Push node out along closest edge.
                    // Need to multiply distance by scale or we'll mess up on scaled box corners.
                    if (px * scalar.x < py * scalar.y) {
                        float sx = Mathf.Sign(dx);
                        localPoint.x =  half.x * sx;
                    } else {
                        float sy = Mathf.Sign(dy);
                        localPoint.y = half.y * sy;
                    }

                    Vector2 hitPos = ci.ltw.MultiplyPoint(localPoint);
                    node.position = hitPos;
                }
            } break;
        }
    }
}

Excellent resource on intersection tests, which explains this calculation a bit better: https://noonat.github.io/intersect/

At this point, you might want to check out the full script on GitHub to see everything with context. Note that it’s also using custom line rendering, explained below.

Rounding the edges on boxes with some circles can make things feel a bit better.

Performance, and the Burst Compiler

Despite fairly aggressive optimization, this rope implementation is still slower than I’m comfortable with:

200 nodes, 80 iterations.

While I’m sure we could squeeze out a bit more performance, the improvement is unlikely to be drastic; I’m fairly sure we’re touching the edges of Unity, C# and its C# / C++ interoperability here.

Got something way faster in C#? Let me know so I can improve this post!

A concern I have here is that the performance impact of the rope is quite “spiky” because we’re updating on a fixed timestep rather than every frame. If we add many more scripts, and bring the baseline CPU time up 14ms or so, players are likely to feel this. We need to either further optimize to make spikes less noticeable, or run rope simulation in a different thread.

My first thought to improve performance was to parallelize the algorithm, but this turns out to not really be very fruitful. I don’t want to talk about this too much, but the critical part is that all granular steps depend on the step before them, so the algorithm would have to be dramatically changed to see any tangible benefit. The extent of these archetypal changes made parallel avenue ultimately not worthwhile for me. If you think it is worthwhile, this GPU cloth simulation might give you some ideas.

Luckily for us, Unity has recently introduced something called Burst, which is a compiler for generating highly optimized native code. To use it, you have to write code in a heavily limited version of C# that only supports basic primitive types (int, float, struct, etc), plus some math types (float2, float3x3, etc). Burst is designed to work within the new C# Job System thing, so you’ll probably get funneled into using that too, unless you want to make life hard, in which case it seems possible to beat it into working outside of it.

200 nodes, 80 iterations – Jobs/Burst version.

Our implementation is pretty data oriented already, so this transition isn’t as difficult as it could be, and the payoff is invaluable. We go from ~2.6ms to ~0.5ms in the above example (>5x speedup!). This post is pretty long already, so I’m not going to walk through the refactor details here–I’ve uploaded a heavily commented jobs system version of the simulation to the GitHub repository for this post, here. On top of the actual cost being less perceptible, the jobs system version actually executes in a separate thread by default, meaning the performance of other scripts won’t pile on top of it and bring the baseline up, as I was concerned about before. This does come at an ergonomic cost–multithreaded code generally does–but in this case the benefits are too important to give up. To maximize this benefit, you’ll naturally want to set the script which executes the job first in Script Execution Order.

Please note that both of these benchmarks represent a good case in terms of collision. With most nodes colliding we see ~3.7ms from the regular version and ~0.8ms from the Jobs/Burst version.

Profiling was done on a Ryzen 1700.

Changing Rope Parameters During a Job

The ergonomic cost of running our code on a separate thread is that we can’t change rope properties at any time during runtime. For example, we can’t change a node constraint while the job is running because the Unity Jobs system considers this type of behavior unsafe. This is really problematic because if we want to use the rope for gameplay, we probably want to change constraints and other rope properties all the time.

There are a few potential workarounds here:

• A command queue which takes all the rope change commands, and then applies them after the job has finished. – 1 frame delay on input.
• Make sure the rope script runs first in Script Execution Order (you should be doing this already), and then only change rope properties in LateUpdate(). – 1 frame delay on input.
• Put scripts which change rope properties even further before the rope script in Script Execution Order. – 0 frame delay on input.

Once implemented, the first approach is the easiest to use, but it comes at the cost of potential garbage collection (if you use lambdas in your implementation) and input delay. The second and third options have next to no implementation cost, but I generally recommend the second for stuff that isn’t mission critical because changing script execution order for everything is annoying. This is what the script in the repo uses.

Render Your Own Line

If you’re lucky, this won’t be a problem.

Unity includes a built-in LineRenderer component which takes a list of vertices and mostly works fine. Sometimes it doesn’t work fine though, and can make some lines pretty ugly:

I love Unity woooo!

It turns out that good line rendering in general is a complicated problem. If you’re interested in why, I highly recommend Matt Deslauriers’ post on it. Cognizant of these complications, I advocate building something that renders our rope well, but doesn’t try to do too much else. Rendering your own line is good if you can’t live with something a bit buggy, want more control, or just want to learn. It’s also a bit faster than LineRenderer.

The line drawing approach is pretty simple. We just want to draw a rectangle between each pair of nodes, and a circle at each node to join them together:

We can render this with just a couple quads for each pair of nodes:

When it comes to actually computing this mesh, the basic solution is iterate through the line and calculate triangles, then create a mesh with the result. This would be fine were we not updating the line each frame. For a rope of 100 nodes (not uncommon for a high quality rope), that’s at least 800 operations (~2 quads per segment) every frame on the game’s main thread. I haven’t tested this, and it would probably run OK, but if we can easily do something better, we should.

If your brain is heading towards “geometry shader” right now, cool! This would be a great use for geometry shaders, but I’ve learned to avoid them as Metal (and so macOS) doesn’t support them, and they can also be quite slow in general. The life of a geometry shader is really quite tragic.

Since our line has a fixed number of vertices, we can sort of imitate a geometry shader by creating a mesh with the right number of vertices from the beginning, and then moving those vertices to the right positions in the vertex shader. It’s not as ergonomic as a geometry shader would be, but it’s pretty fast and works on all platforms.

Here’s a more concrete version of what we need to do:

1. C# / Unity: Create a mesh with the right number of vertices (totalNodes * 8).
2. C# / Unity: Calculate and assign triangle indices.
3. Vertex Shader: Figure out which vertices relate to which rope segments, and move them to the right place.

The first and second are both part of creating the mesh. The main thing to remember when calculating triangle indices is that Unity uses a clockwise winding order, so we want our triangle indices to rotate clockwise to indicate they’re facing the camera and shouldn’t get culled;

Read more about winding and face culling order here.

Mesh mesh = new Mesh();
{
    Vector3[] vertices = new Vector3[totalNodes * VERTICES_PER_NODE];
    int[] triangles = new int[totalNodes * TRIANGLES_PER_NODE * 3];

    for (int i = 0; i < totalNodes; i++) {
        // 4 triangles per node, 3 indices per triangle.
        int idx = i * TRIANGLES_PER_NODE * 3;
        // 8 vertices per node.
        int vIdx = i * VERTICES_PER_NODE;

        // Rect between segments.
        triangles[idx + 0] = vIdx;        // v1 top
        triangles[idx + 1] = vIdx+1;      // v2 bottom
        triangles[idx + 2] = vIdx+2;      // v1 bottom
        triangles[idx + 3] = vIdx;        // v1 top
        triangles[idx + 4] = vIdx+3;      // v2 top
        triangles[idx + 5] = vIdx+1;      // v2 bottom

        // End cap quad.
        triangles[idx + 6] = vIdx+4;      // tl
        triangles[idx + 7] = vIdx+7;      // br
        triangles[idx + 8] = vIdx+6;      // bl
        triangles[idx + 9] = vIdx+4;      // tl
        triangles[idx + 10] = vIdx+5;     // tr
        triangles[idx + 11] = vIdx+7;     // br
    }

    // We only really care about the number of vertices, not what they actually are -- the positions aren't used.
    mesh.vertices = vertices;
    mesh.triangles = triangles;
    // Since we pretty much want the rope to always render (it's always going to be on screen if it's active), we
    // just set the bounds super large to avoid recalculating the bounds when the rope changes.
    mesh.bounds = new Bounds(Vector3.zero, Vector3.one * 100f);
}

And here’s a stripped version of the moving shader – check the full version on GitHub here.

v2f vert (appdata v) {
    v2f o;
    o.uv = float2(0, 0);

    // The node that the current vertex is associated with.
    int idx = v.id / VERTICES_PER_NODE;
    // The next node, clamped to the max number of nodes.
    int next_idx = min(MAX_NODE_COUNT-1, idx+1);
    float4 p1 = _Points[idx];
    float4 p2 = _Points[next_idx];
    int id = v.id % VERTICES_PER_NODE;

    float2 dir = normalize(p2.xy - p1.xy);
    float2 perp = float2(-dir.y, dir.x);   // Counter-clockwise perpendicular to dir.

    // Currently, each line segment has 8 vertices -- 4 for the line and 4 for the start cap.
    // Comments are written as though p1 -> p2 is going left to right.
    float2 pos;
    if (id == 0) {          // Vertex 1, v1 top.
        pos = p1.xy + perp * _Width;
    } else if (id == 1) {   // Vertex 2, v2 bottom.
        pos = p2.xy - perp * _Width;
    } else if (id == 2) {   // Vertex 3, v1 bottom.
        pos = p1.xy - perp * _Width;
    } else if (id == 3) {   // Vertex 4, v2 top.
        pos = p2.xy + perp * _Width;

    } else if (id == 4) {   // Vertex 5, cap tl.
        pos = p1.xy + float2(-_Width, _Width);
        o.uv = float2(0, 1);
    } else if (id == 5) {   // Vertex 6, cap tr.
        pos = p1.xy + float2(_Width, _Width);
        o.uv = float2(1, 1);
    } else if (id == 6) {   // Vertex 7, cap bl.
        pos = p1.xy + float2(-_Width, -_Width);
        o.uv = float2(0, 0);
    } else if (id == 7) {   // Vertex 8, cap br.
        pos = p1.xy + float2(_Width, -_Width);
        o.uv = float2(1, 0);
    }

    o.clipPos = mul(UNITY_MATRIX_VP, float4(pos, 0, 1));

    return o;
}

fixed4 frag (v2f i) : SV_Target {
    float4 col;
    // Could replace this `if` easily with lerp, but this is more readable for now.
    if (i.endCap) {
        float dist = distance(i.uv, float2(0.5, 0.5));
        col = _Color;
        col.a = step(0.5, 1.0 - dist);
    } else {
        col = _Color;
    }

    return col;
}

Experienced developers, don’t be too upset at me for manually getting id in the shader, and then using an if ... else chain to move vertices. This code is plenty fast (~0.006ms in RenderDoc) and serves its purpose in a straightforward way.

For those wanting something more efficient, or wondering on best practices, the best way to do this is to assign the right information to vertices directly using SetVertexBufferParams() to avoid the if ... else chain. Non-Unity users, look for something related to VertexAttributes in your engine / graphics library.

Questions

I downloaded the example project off GitHub and I get errors about float2 not existing and stuff like that.

Make sure the Burst package is installed. This post was written using version 1.2.3. (In the Unity editor: Window -> Package Manager -> All Packages (in the dropdown) -> Search for Burst)

In the non-Burst version, aren’t structs faster than classes?

In my testing, marginally (~5%). This seems worth doing in production, and is even required for using the burst compiler, but adds noise to the code snippets in the post, so I decided not to include this optimization in writing. The Burst version in the repo uses structs.

In SnapshotCollisions(), isn’t it wasteful to throw away old CollisionInfos?

If your colliders are static, yes. You could optimize this for a large number of colliders by implementing some sort of cache which holds CollisionInfos for longer than a physics tick if they’re used frequently. Even if they aren’t static, I’m sure there’s gains to be had from only updating changed data such as position.

Having said that, SnapshotCollision() only takes about ~0.2ms on my machine, so profile first to check if this is actually worth doing.

The Rope.cs version on GitHub doesn’t use FixedUpdate() like in the example snippet, what gives?

The GitHub version uses a custom fixed update cycle rather than the built-in FixedUpdate(). The primary reason for this is control. If rope is an important mechanic in your game, it can be useful to be able to change its tick rate independently from regular physics. I also haven’t talked about any interpolation here, so I really wanted to provide a custom update implementation.

A custom update is also required for the Jobs version, so we save ourselves some work on the refactor.

Collision doesn’t work properly when sprites are using SpriteDrawMode.Tiled or SpriteDrawMode.Sliced.

This is because Unity has decided to separate this property entirely from the transform, and scales sprites all on its own. This means we can have an oddly scaled sprite even with a scale of (1, 1, 1). I’m sure there’s a good reason for this, but it’s really annoying.

To remedy this we can manually create the transformation matrix with the scale adjusted when we snapshot collisions:

CollisionInfo ci = collisionInfos[numCollisions];
ci.id = id;
ci.scale.x = math.length(ci.ltw.c0.xyz);
ci.scale.y = math.length(ci.ltw.c1.xyz);
ci.position = (Vector2) col.transform.position;
ci.numCollisions = 1; // 1 collision, this one.

var sr = col.GetComponent<SpriteRenderer>();
if (sr != null && sr.drawMode != SpriteDrawMode.Simple) {
    ci.scale.x *= sr.size.x;
    ci.scale.y *= sr.size.y;
    ci.ltw = float4x4.TRS(col.transform.position, col.transform.rotation, math.float3(ci.scale.x, ci.scale.y, 1f));
    ci.wtl = math.inverse(ci.ltw);
} else 
    ci.wtl = col.transform.worldToLocalMatrix;
    ci.ltw = col.transform.localToWorldMatrix;
}

This isn’t without issue. For some reason the “real” collider is slightly bigger than what we arrive at with a manually constructed matrix:

My guess is that this is related to slice boundaries.

Another solution is to just have the collider separate from the sprite and scale it normally.

The Collider2D.offset property doesn’t work.

The offset property doesn’t work because the collision code hasn’t implemented it. If you need offset, you can implement it quite easily for boxes by first of all adding a CollisionInfo.offset property, and then applying it at the appropriate point in collision:

// Box collision:

// If distance from center is more than box "radius", then we can't be colliding.
Vector2 half = ci.colliderSize * .5f;
Vector2 scalar = ci.scale;
//float dx = localPoint.x;
float dx = localPoint.x - ci.offset.x;
float px = half.x - Mathf.Abs(dx);
if (px <= 0) {
    continue;
}

//float dy = localPoint.y;
float dy = localPoint.y - ci.offset.y;
float py = half.y - Mathf.Abs(dy);
if (py <= 0) {
    continue;
}

// Need to multiply distance by scale or we'll mess up on scaled box corners.
if (px * scalar.x < py * scalar.y) {
    float sx = Mathf.Sign(dx);
    //localPoint.x = half.x * sx;
    localPoint.x = ci.offset.x + half.x * sx;
} else {
    float sy = Mathf.Sign(dy);
    //localPoint.y = half.y * sy;
    localPoint.y = ci.offset.y + half.y * sy;
}

Note that offset is in local space, so we can’t easily apply it to Circle colliders with the provided implementation. You’ll need to switch to something which transforms to local space (slow), like in the box collision method.

How can I prevent tunneling?

My first and easiest suggestion is to try to reduce maxSimMove and decrease step time. This should reduce tunneling by stopping nodes from moving too much in a single step. However, if your colliders are small or you need a particularly fast moving rope, then this isn’t a good solution.

Ideally we’d raycast between the previous and current position to detect and prevent tunneling. This is pretty complicated, and very slow if done naively. We’d probably have to implement some kind of raycasting ourselves!

The best quick and dirty solution I’ve got for you is to keep track of node positions before adjusting constraints, and then do multiple collision checks at the collision phase (AdjustCollisions()), incrementing from the previous positions to the new position until a collision is found (if any). This should stop tunneling with a small enough increment. To take this idea to the next level, you probably want to implement a line intersection test (i.e. raycasting).

Learnings From The Future

2025-08-07

I got the chance to implement (more like fix) a 3D cloth sim in production using some of these learnings. Along the way, many more learnings were had, which I’m going to share here in the hopes that they might save you some time. I’m mostly talking about cloth here, but I think most advice will apply to rope as well.

Teleporting

In games, we teleport players and objects around a lot; loading things in, positioning things for cutscenes, rotating to look at things, etc. This has high potential of doing things with your rope/cloth that make it look janky and bad!

To stay on top of this, you want to exert as much control over your simulation as possible. For cloth at least (which is usually attached to something) this means simulating in local space. Then, when the player moves/rotates/jumps you manually inject that as an external force into the sim.

With this newfound supervision over the sim, you can even and can even make creative decisions such as how much rotation should affect things in comparison to movement, or how much of the player’s animation goes into the movement of the cloth.

You’ll still have issues with dramatic changes to the local space though (e.g. snapping to different animations). For our game, this mostly happens in transitional periods, so I was able to implement a Settle() function which just steps the simulation a fixed number of times on the spot. Far from perfect, but reasonable.

Performance/Make It Less Stretchy

As you increase the number of nodes, it becomes more and more difficult to manage the “stretchyness” of the spring without nuking performance. An answer here is to layer in a new type of constraint—the hard constraint. Hard constraints are meant to be solved in a specific order (e.g. top to bottom) and instead of moving both vertices an equal amount toward each other, we just move the bottom one the full distance to the top. This way, the “length” of the rope/cloth can be solved in just 1 iteration.

In this system, the update loop looks something like this:

• Calculate external forces.
• Step (some number of times).
  • Apply external forces.
  • Update integration.
  • Iterate (as many times as suitable).
    • Process collision.
    • Process stretch constraints.
    • Process hard constraints.
  • Process collision one more time.
• Step one more time, and interpolate towards the result.

Great article with some more pertinent information here: https://www.gamedeveloper.com/programming/the-secrets-of-cloth-simulation-in-i-alan-wake-i-.

For cloth, the order that you apply your constraints can be important even if we’re just talking about stretch constraints. I’m not sure if there is a right way to do it, but I ended up just averaging the post-constraint positions to stop it mattering.

You Really Want To Interpolate

A fixed timestep is definitely the way to go, but does come with some obstacles. Unless you’re stepping your simulation faster than the game’s framerate, you’ll might see your rope/cloth clipping through collision objects, particularly during continuous movement (e.g. a character raising their knee while wearing a dress). There’s also the obvious one of the simulation being jittery because it doesn’t match the game’s framerate.

Interpolation solves most of the headaches here. Basically, you run 1 more tentative simulation step every frame, and then blend towards that result for rendering. Next frame, you throw that tentative step away and do it again. Not only does this effectively make the simulation perfectly smooth, but it means you get some response on the first frame that the action (collider moving, wind force, etc) happens.

Check out Fix Your Timestep! for a more detailed explanation (near the bottom).

I’ve also seen people step collision every frame regardless of interpolation, to make super sure that frame is presented with any clipping. I don’t feel like this is a bad option if avoiding clipping is very important for you, even if it does mess with the simulation a bit.

There’s a Hitman Paper

Turns out the first Hitman game used Verlet integration for its physics. It covers Verlet integration in much more depth and is probably one of the best resources out there that I didn’t know about at the time of writing.

• https://graphics.cs.cmu.edu/nsp/course/15-869/2006/papers/jakobsen.htm

A good rule is to never call Instantiate() when the player has control.

A Dead Simple Pool

Here’s a simple, performant pool you can use:

public class Pool : MonoBehaviour {
    [Serializable] // Let this appear in the inspector.
    public class ObjectPool {
        public int amount;
        public PooledObject objectToPool;
    }

    // Singleton boilerplate.
    private static Pool _instance;
    public static Pool Instance {
        get {
            if (!_instance) {
                _instance = FindObjectOfType<Pool>();
            }

            return _instance;
        }
    }

    // List of objects to pool (only used for instantiation)
    public List<ObjectPool> objectPools;

    // Pool of objects, indexed by instance ID.
    // A queue works pretty naturally here.
    private Dictionary<int, Queue<PooledObject>> pool;

    private void Awake() {
        // Spawn all objects in provided pools.
        pool = new Dictionary<int, Queue<PooledObject>>();
        foreach (ObjectPool objPool in objectPools) {
            int amount = objPool.amount;
            PooledObject obj = objPool.objectToPool;

            // Saved prefabs have an instance id, which we can use to talk about the same prefab from other scripts.
            int id = obj.GetInstanceID();
            Queue<PooledObject> queue = new Queue<PooledObject>(amount);
            for (int i = 0; i < amount; i++) {
                var clone = Instantiate(obj, transform);
                clone.id = id;
                clone.Finished += ReQueue;      // When `Finish()` is called, we put our object back in the queue.
                clone.gameObject.SetActive(false);
                queue.Enqueue(clone);
            }

            pool.Add(id, queue);
        }
    }

    private PooledObject GetNextObject(PooledObject obj) {
        // @NOTE: create a new queue if none exists, for pooling "unplanned" objects?
        var queue = pool[obj.GetInstanceID()];
        PooledObject clone = null;
        // If queue is empty (has been exhausted -- the pool size was too small), extend the queue by instantiating a new object,
        // and add it to the future queue.
        if (queue.Count == 0) {
            Debug.LogWarning("Object Pool queue was empty; wasn't able to get a new pooled object, so one will be instatiated.");
            clone = Instantiate(obj, transform);
            clone.id = obj.GetInstanceID();
            clone.Finished += ReQueue;
            clone.gameObject.SetActive(false);
        } else {
            clone = queue.Dequeue();
        }

        return clone;
    }

    // Gets an object from the pool and returns it after setting position, rotation, and active.
    public PooledObject Spawn(PooledObject obj, Vector3 position, Quaternion rotation) {
        var clone = GetNextObject(obj);
        clone.transform.position = position;
        clone.transform.rotation = rotation;
        clone.gameObject.SetActive(true);
        return clone;
    }

    private void ReQueue(PooledObject obj) {
        // Hide object and insert back in queue for reuse.
        obj.gameObject.SetActive(false);
        var queue = pool[obj.id];
        queue.Enqueue(obj);
    }
}

PooledObject is teeny tiny:

public class PooledObject : MonoBehaviour {
    [HideInInspector]
    public int id;
    public Action<PooledObject> Finished;

    // A component reference for fast access -- avoids calls to GetComponent<>().
    public Component behaviour;

    public T As<T>() where T: Component {
        return behaviour as T;
    }

    public void Finish() {
        if (Finished != null) {
            Finished(this);
        }
    }

    // Convenience method to call finish when particles finish.
    // Needs ParticleSystem stop action to be set to "Callback".
    private void OnParticleSystemStopped() {
        Finish();
    }
}

Usage

Usage is as straightforward as possible. Create a new Game Object in your scene and attach the Pool script. Then, attach the PooledObject script to any prefabs that you want to be pooled, and drag them into the object pools list, with a best-guess for how many will be used concurrently:

If you exceed the amount in the object pool, new ones will be spawned with Instantiate() rather than failing.

Then, instead of calling Instatiate() and Destroy(), we call Pool.Spawn() and PooledObject.Finish():

public class ProjectileSpawner : MonoBehaviour {
    public float spawnRate = 0.1f;
++  public PooledObject projectile;
--  public Projectile projectile;

    private float timer = 0f;

    private void Update() {
        timer += Time.deltaTime;
        if (timer > spawnRate) {
            timer -= spawnRate;

            // Spawn object with random 2D rotation.
++          PooledObject instance =
++              Pool.Instance.Spawn(projectile, transform.position, Quaternion.Euler(0f, 0f, Random.Range(0f, 360f)));
            // We can avoid GetComponent<>() for a frequently accessed component, which is nice.
++          instance.As<Projectile>().speed = Range.Range(.5f, 1f);

--          Projectile instance =
--              Instantiate(projectile, transform.position, Quaternion.Euler(0f, 0f, Random.Range(0f, 360f)));
--          instance.speed = Random.Range(.5f, 1f);
        }
    }
}

public class Projectile : MonoBehaviour {
    ...
    private void OnTriggerEnter2D(Collider2D other) {
        ...

++      GetComponent<PooledObject>().Finish();
--      Destroy(gameObject);
    }
}

It would be better to cache the PooledObject component. GetComponent<>() has been used here for simplicity.

Instantiate() doesn’t care, but SetActive() does

The really nice thing about using Instatiate() and Destroy() is that you don’t have to worry about any kind of previous state on the object – everything is new and fresh. If you’re disabling and re-enabling objects (like in a pool), you do have to pay attention to object state; particle progress, animations, and any variables changed on components can all trip you up. There are ways you could reset components to fresh (serialization), but if you want to keep your performance intact, this is just something that you’re going to have to eat, sorry.

The Numbers

What good is an optimization without profiling?

I’m testing this with a modified version of the above ProjectileSpawner code. To avoid variance, I’ve removed the randomness and some other stuff;

public class BenchmarkProjectileSpawner: MonoBehaviour {
    public float delay = 5f;
    public int amount = 5000;

    // Pool variant.
    public PooledObject projectile;
    -------------------------------
    // Instantiate variant.
    public GameObject projectile;

    private float timer = 0f;

    // These probably allocate, so cache them for benchmarking.
    private Vector3 position = Vector3.zero;
    private Quaternion rotation = Quaternion.identity;

    // Update is called once per frame
    private void Update() {
        timer += Time.deltaTime;
        if (timer > delay) {
            // Only fire once.
            timer = -Mathf.Infinity;
            for (int i = 0; i < amount; i++) {
                // Pool variant.
                Pool.Instance.Spawn(projectile, position, rotation);
                -----------------------------------------------------------
                // Instantiate variant.
                Instantiate(projectile, position, rotation);
            }
        }
    }
}

public class BenchmarkProjectile : MonoBehaviour {
    public float speed = 1f;

    private PooledObject pooledObject;

    private float timer = 0f;
    private Vector2 up = Vector2.up;

    private void Awake() {
        pooledObject = GetComponent<PooledObject>();
    }

    private void Update() {
        transform.Translate(up * speed * Time.deltaTime);

        timer += Time.deltaTime;
        if (timer > 2f) {
            timer = 0f;
            // Pool variant.
            pooledObject.Finish();
            ------------------------
            // Instantiate variant.
            Destroy(gameObject);
        }
    }
}

The test is pretty basic. We spawn 5,000 projectiles with either Instantiate() or Pool.Spawn(), and observe the results through the built-in profiler. We’ll also have a look at differences in destruction times between the two approaches.

These results aren’t on-the-nose accurate – I’m running in editor, and I’m only eyeballing the variance. They’re more than enough, however, to get the point across;

Instatiate()/Destroy() profiler

Object pool profiler

The results are in!

Spawning 5,000 projectiles was enough to make us drop a couple of frames even with our object pool. With Instantiate(), it’s closer to a freeze. When spawning lots of objects in one place, you probably always want to split the operation over multiple frames, regardless of how optimized your architecture is. Even a small amount of stutter in games is horrible and really goes against “game feel” – even if players can’t point out why, they’ll feel uncomfortable playing your game.

If you’re thinking: “Why would I ever want to spawn thousands of objects at once? Instantiate() is good enough.”, here’s some things to consider:

• You might not spawn that many objects from any one place at the same time, but as your game gets bigger you can end up spawning a significant number of objects at the same time either by coincidence, or because an in-game event triggers a bunch of things at once; e.g. AI enemies shooting at a player.
• The objects I’ve used in this benchmark are pretty much as simple as they come – only a few (basic) components and no children. Add a couple Rigidbodys, character animations, and child objects, and the number of things you can spawn without players feeling anything drops hard.
• PC (where this benchmark was run) is probably the fastest platform you’ll be running your game on. Spawning even a couple of fat objects on mobile can be enough to cause a stutter.

An object pool significantly increases your headroom for spawning lots of objects at runtime, and is almost as convenient as instantiation. If you’re calling Instantiate(), chances are that it can be replaced with an object pool.

Source code and Unity project available at https://github.com/Toqozz/blog-code/tree/master/object_pool.

In the right circumstances, GPU instancing can allow you to feasibly draw even millions of meshes. Unity tries to make this work automatically for you if it can. If all your meshes use the same material, ‘GPU Instancing’ is ticked, your shader supports instancing, lighting and shadows play nicely, you’re not using a skinned mesh renderer, etc, Unity will automatically batch meshes into a single draw call.

A low number of draw calls is usually a sign of a well-performing game. For each new draw call, the GPU has to do a context switch, which is expensive.

There’s a lot of ifs and buts here, which is a pain in the ass if you just want to write performant code, and even if you do get GPU instancing to work, the overhead of GameObjects and Transforms alone is huge.

DrawMeshInstanced()

You can use Graphics.DrawMeshInstanced() to get around a lot of these conditions. This will draw a number of meshes (up to 1023 in a single batch) for a single frame.

This is a particularly nice solution for when you want to draw a lot of objects that don’t move very much, or only move in the shader (trees, grass). It allows you to easily shove meshes to the GPU, customize them with MaterialPropertyBlocks, and avoid the fat overhead of GameObjects. Additionally, Unity has to do a little less work to figure out if it can instance the objects or not, and will throw an error rather than silently nerfing performance. The main downside here though is that moving these objects usually results in a huge for loop, which kills performance.

If you must move meshes while using DrawMeshInstanced(), consider using a sleep/wake model to reduce the size of these loops as much as possible.

Example

public class DrawMeshInstancedDemo : MonoBehaviour {
    // How many meshes to draw.
    public int population;
    // Range to draw meshes within.
    public float range;

    // Material to use for drawing the meshes.
    public Material material;
  
    private Matrix4x4[] matrices;
    private MaterialPropertyBlock block;

    private Mesh mesh;

    private void Setup() {
        Mesh mesh = CreateQuad();
        this.mesh = mesh;

        matrices = new Matrix4x4[population];
        Vector4[] colors = new Vector4[population];

        block = new MaterialPropertyBlock();

        for (int i = 0; i < population; i++) {
            // Build matrix.
            Vector3 position = new Vector3(Random.Range(-range, range), Random.Range(-range, range), Random.Range(-range, range));
            Quaternion rotation = Quaternion.Euler(Random.Range(-180, 180), Random.Range(-180, 180), Random.Range(-180, 180));
            Vector3 scale = Vector3.one;

            mat = Matrix4x4.TRS(position, rotation, scale);

            matrices[i] = mat;

            colors[i] = Color.Lerp(Color.red, Color.blue, Random.value);
        }

        // Custom shader needed to read these!!
        block.SetVectorArray("_Colors", colors);
    }

    private Mesh CreateQuad(float width = 1f, float height = 1f) {
        // Create a quad mesh.
        // See source for implementation.
    }

    private void Start() {
        Setup();
    }

    private void Update() {
        // Draw a bunch of meshes each frame.
        Graphics.DrawMeshInstanced(mesh, 0, material, matrices, population, block);
    }
}

Essentially, we fill a big array with matrices representing object transforms (position, rotation, scale) and then pass that array to Graphics.DrawMeshInstanced(), which will assign those matrices in the shader automagically (assuming the shader supports instancing).

You can still grab the instanceID to do per-mesh customizations via MaterialPropertyBlocks (see color array), but you’ll probably need to use a custom shader:

A custom shader is only required if you’re customizing per-mesh properties.

Shader "Custom/InstancedColor" {
    SubShader {
        Tags { "RenderType" = "Opaque" }

        Pass {
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #pragma multi_compile_instancing

            #include "UnityCG.cginc"

            struct appdata_t {
                float4 vertex   : POSITION;
                float4 color    : COLOR;
                UNITY_VERTEX_INPUT_INSTANCE_ID
            };

            struct v2f {
                float4 vertex   : SV_POSITION;
                fixed4 color    : COLOR;
            }; 

            float4 _Colors[1023];   // Max instanced batch size.

            v2f vert(appdata_t i, uint instanceID: SV_InstanceID) {
                // Allow instancing.
                UNITY_SETUP_INSTANCE_ID(i);

                v2f o;
                o.vertex = UnityObjectToClipPos(i.vertex);
                o.color = float4(1, 1, 1, 1);

                // If instancing on (it should be) assign per-instance color.
                #ifdef UNITY_INSTANCING_ENABLED
                    o.color = _Colors[instanceID];
                #endif

                return o;
            }

            fixed4 frag(v2f i) : SV_Target {
                return i.color;
            }

            ENDCG
        }
    }
}

1022 meshes with the standard shader. 1022 meshes with a custom shader, and per-mesh colors

Note that shadows are missing on the colored version. This is because we’re using a custom shader to apply the colors which doesn’t have a shadow pass. Have a look at this for some examples of adding shadow casting/receiving to a custom shader.

If setting up a random array in the shader feels awkward, that’s because it is. There doesn’t seem to be a way to get Unity to set up an array for you and index the color automatically. If we were using individual game objects, we could do something like this. You could probably get this to work by digging into the shader source and having a look at what names Unity uses for the arrays, but that’s pretty convoluted for no good reason.

DrawMeshInstancedIndirect()

DrawMeshInstanced() turns out to be a sort of wrapper around DrawMeshInstancedIndirect(). You can achieve everything in the latter that you can with the former (and vice versa, with complications). DrawMeshInstanced() is mainly a friendly way to draw meshes without touching the GPU.

Naturally, some nice things get lost in the abstraction. First of all, the Indirect variant allows you to bypass the 1023 mesh limit and draw as many meshes as you like in a single batch (the 1023 mesh limit seems to actually inherited from MaterialPropertyBlock). The primary benefit, however, is that you can offload the entirety of the work onto the GPU. With DrawMeshInstanced(), Unity has to upload the array of mesh matrices to the GPU each frame, whereas DrawMeshInstancedIndirect() creates and stores data on the GPU indefinitely. This also means using GPU-based structures to store data, mainly ComputeBuffers, which can be scary up front but turns out to be more convenient, and opens the door to some easy mass parallelisation via compute shaders.

Example

Here’s the same program as above but using DrawMeshInstancedIndirect() instead:

public class DrawMeshInstancedIndirectDemo : MonoBehaviour {
    public int population;
    public float range;

    public Material material;

    private ComputeBuffer meshPropertiesBuffer;
    private ComputeBuffer argsBuffer;

    private Mesh mesh;
    private Bounds bounds;

    // Mesh Properties struct to be read from the GPU.
    // Size() is a convenience funciton which returns the stride of the struct.
    private struct MeshProperties {
        public Matrix4x4 mat;
        public Vector4 color;

        public static int Size() {
            return
                sizeof(float) * 4 * 4 + // matrix;
                sizeof(float) * 4;      // color;
        }
    }

    private void Setup() {
        Mesh mesh = CreateQuad();
        this.mesh = mesh;

        // Boundary surrounding the meshes we will be drawing.  Used for occlusion.
        bounds = new Bounds(transform.position, Vector3.one * (range + 1));

        InitializeBuffers();
    }

    private void InitializeBuffers() {
        // Argument buffer used by DrawMeshInstancedIndirect.
        uint[] args = new uint[5] { 0, 0, 0, 0, 0 };
        // Arguments for drawing mesh.
        // 0 == number of triangle indices, 1 == population, others are only relevant if drawing submeshes.
        args[0] = (uint)mesh.GetIndexCount(0);
        args[1] = (uint)population;
        args[2] = (uint)mesh.GetIndexStart(0);
        args[3] = (uint)mesh.GetBaseVertex(0);
        argsBuffer = new ComputeBuffer(1, args.Length * sizeof(uint), ComputeBufferType.IndirectArguments);
        argsBuffer.SetData(args);

        // Initialize buffer with the given population.
        MeshProperties[] properties = new MeshProperties[population];
        for (int i = 0; i < population; i++) {
            MeshProperties props = new MeshProperties();
            Vector3 position = new Vector3(Random.Range(-range, range), Random.Range(-range, range), Random.Range(-range, range));
            Quaternion rotation = Quaternion.Euler(Random.Range(-180, 180), Random.Range(-180, 180), Random.Range(-180, 180));
            Vector3 scale = Vector3.one;

            props.mat = Matrix4x4.TRS(position, rotation, scale);
            props.color = Color.Lerp(Color.red, Color.blue, Random.value);

            properties[i] = props;
        }

        meshPropertiesBuffer = new ComputeBuffer(population, MeshProperties.Size());
        meshPropertiesBuffer.SetData(properties);
        material.SetBuffer("_Properties", meshPropertiesBuffer);
    }

    private Mesh CreateQuad(float width = 1f, float height = 1f) {
        ...
    }

    private void Start() {
        Setup();
    }

    private void Update() {
        Graphics.DrawMeshInstancedIndirect(mesh, 0, material, bounds, argsBuffer);
    }

    private void OnDisable() {
        // Release gracefully.
        if (meshPropertiesBuffer != null) {
            meshPropertiesBuffer.Release();
        }
        meshPropertiesBuffer = null;

        if (argsBuffer != null) {
            argsBuffer.Release();
        }
        argsBuffer = null;
    }
}