🌊 Lesson 3.5: Mini-Project — A Burst-Compiled Parallel Field Simulation

The Plan

The per-frame loop is the same shape you learned in Lesson 3.2, now with a parallel Burst job in the middle:

No per-point GameObject, no Transform, no Update on thousands of components — just arrays flowing through a job into a draw call. This is the data-oriented shape, and it's a stone's throw from how ECS does it (which is Module 4).

Step 1: Setup & the Grid

1. Create an empty scene. Add an empty GameObject named RippleField.
2. Make a new script RippleField.cs and add it to that object.
3. We'll expose a grid size, spacing, wave parameters, plus a mesh and material (assign a Cube mesh and a URP/Lit material with Enable GPU Instancing ticked).

In Start() we allocate two Persistent native arrays once — the immutable grid coordinates and the per-frame output matrices — and fill the grid:

using Unity.Collections;
using Unity.Mathematics;
using UnityEngine;

public class RippleField : MonoBehaviour
{
    [SerializeField] int gridSize = 160;      // 160 x 160 = 25,600 points
    [SerializeField] float spacing = 1f;
    [SerializeField] float amplitude = 4f;
    [SerializeField] float frequency = 0.25f;
    [SerializeField] float scale = 0.8f;
    [SerializeField] Mesh mesh;
    [SerializeField] Material material;

    NativeArray<float2> gridXZ;        // packed, immutable — allocate once
    NativeArray<float4x4> matrices;    // packed output — reused each frame
    int count;

    void Start()
    {
        count = gridSize * gridSize;
        gridXZ   = new NativeArray<float2>(count, Allocator.Persistent);
        matrices = new NativeArray<float4x4>(count, Allocator.Persistent);

        float half = gridSize * 0.5f;
        for (int i = 0; i < count; i++)
        {
            int x = i % gridSize, z = i / gridSize;
            gridXZ[i] = new float2((x - half) * spacing, (z - half) * spacing);
        }
    }
    // ... job + Update + cleanup below ...
}

Step 2: The Burst Wave Job

The job is a Burst-compiled IJobParallelFor. It reads a point's grid coordinate and the current time, computes an animated height, and writes a full transform matrix to that point's slot — obeying the parallel-write rule (each index writes only matrices[index]):

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;

[BurstCompile]
struct WaveJob : IJobParallelFor
{
    [ReadOnly] public NativeArray<float2> gridXZ;   // shared read
    public float time, amplitude, frequency, scale;
    [WriteOnly] public NativeArray<float4x4> matrices;  // this job's output

    public void Execute(int index)
    {
        float2 p = gridXZ[index];
        // an animated ripple: height from two travelling sine waves
        float height = amplitude *
            math.sin(p.x * frequency + time) *
            math.cos(p.y * frequency + time);

        float3 pos = new float3(p.x, height, p.y);
        matrices[index] = float4x4.TRS(pos, quaternion.identity, scale);
    }
}

Everything in Execute is Burst-friendly: float2/float3/float4x4 math and nothing managed. Burst will vectorise the sine/cosine work and inline the matrix build.

Step 3: Schedule & Render Each Frame

In Update() we schedule the job across all cores, complete it, then draw every matrix in instanced batches. Graphics.RenderMeshInstanced (Unity 6) accepts a NativeArray<Matrix4x4>; since float4x4 and Matrix4x4 share the same 64-byte column-major layout, we Reinterpret the array at zero cost:

void Update()
{
    var job = new WaveJob {
        gridXZ    = gridXZ,
        time      = Time.time,
        amplitude = amplitude,
        frequency = frequency,
        scale     = scale,
        matrices  = matrices
    };

    // one iteration per point, batch of 64 — parallel + Burst
    JobHandle handle = job.Schedule(count, 64);
    handle.Complete();                       // results needed to draw this frame

    // float4x4 and Matrix4x4 are layout-identical — reinterpret, no copy
    var drawMatrices = matrices.Reinterpret<Matrix4x4>();

    var rp = new RenderParams(material);
    Graphics.RenderMeshInstanced(rp, mesh, 0, drawMatrices);
}

That's the entire runtime: schedule, complete, draw. The main thread stays thin because the heavy work is on the workers, and the draw is a handful of instanced submissions rather than 25,600 individual ones.

Step 4: Cleanup

Persistent native memory must be freed on teardown, or leak detection will (rightly) complain:

void OnDestroy()
{
    if (gridXZ.IsCreated)   gridXZ.Dispose();
    if (matrices.IsCreated) matrices.Dispose();
}

Guarding with IsCreated avoids a double-dispose if the object is torn down before Start ran. That's the complete resource lifecycle: allocate once in Start, reuse every Update, free in OnDestroy.

The Full Script

Everything assembled:

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;
using UnityEngine;

public class RippleField : MonoBehaviour
{
    [SerializeField] int gridSize = 160;
    [SerializeField] float spacing = 1f, amplitude = 4f, frequency = 0.25f, scale = 0.8f;
    [SerializeField] Mesh mesh;
    [SerializeField] Material material;

    NativeArray<float2> gridXZ;
    NativeArray<float4x4> matrices;
    int count;

    void Start()
    {
        count = gridSize * gridSize;
        gridXZ   = new NativeArray<float2>(count, Allocator.Persistent);
        matrices = new NativeArray<float4x4>(count, Allocator.Persistent);
        float half = gridSize * 0.5f;
        for (int i = 0; i < count; i++)
        {
            int x = i % gridSize, z = i / gridSize;
            gridXZ[i] = new float2((x - half) * spacing, (z - half) * spacing);
        }
    }

    void Update()
    {
        var handle = new WaveJob {
            gridXZ = gridXZ, time = Time.time,
            amplitude = amplitude, frequency = frequency, scale = scale,
            matrices = matrices
        }.Schedule(count, 64);
        handle.Complete();

        var rp = new RenderParams(material);
        Graphics.RenderMeshInstanced(rp, mesh, 0, matrices.Reinterpret<Matrix4x4>());
    }

    void OnDestroy()
    {
        if (gridXZ.IsCreated)   gridXZ.Dispose();
        if (matrices.IsCreated) matrices.Dispose();
    }

    [BurstCompile]
    struct WaveJob : IJobParallelFor
    {
        [ReadOnly] public NativeArray<float2> gridXZ;
        public float time, amplitude, frequency, scale;
        [WriteOnly] public NativeArray<float4x4> matrices;
        public void Execute(int index)
        {
            float2 p = gridXZ[index];
            float height = amplitude *
                math.sin(p.x * frequency + time) *
                math.cos(p.y * frequency + time);
            matrices[index] = float4x4.TRS(new float3(p.x, height, p.y),
                                           quaternion.identity, scale);
        }
    }
}

Press Play and you'll see a rolling wave of 25,600 cubes running smoothly — because none of it goes through the GameObject machinery. Open the Profiler and you'll find the WaveJob spread across the worker lanes each frame while the main thread barely registers it.

Tuning & Extending

• Push the count. Raise gridSize to 256 (65,536 points) and watch it stay smooth. Then toggle Jobs ▸ Burst ▸ Enable Compilation off and feel the frame time jump — that's Burst earning its keep.
• Batch count. Try 16, 64, 256 and profile. The sweet spot balances scheduling overhead against load balancing.
• Colour it. Pass a per-instance colour via a MaterialPropertyBlock / instanced property driven by height for the heat-map look.
• Overlap frames. Move Complete() to LateUpdate and do other work between schedule and complete.

Quick Quiz

Summary

🚀 What's Next?

You've built a data-oriented simulation by hand. In Module 4 we hand that pattern to a framework: the Entity Component System. Lesson 4.1 already introduced the mindset and showed the payoff render — now you'll build it, starting with real components and archetypes.