A hill, wall, chokepoint, or dark corner is not automatically useful. It becomes useful when it changes movement, visibility, or risk. That is why terrain analysis matters: it turns the map into data that an AI can evaluate.

The basic question

The core question is simple:

Which parts of this map give one side an advantage?

That question is more useful than a hand-authored list of “important” spots. Hard-coded regions are fragile. They break when the map changes, when the level is procedural, or when the tactical situation shifts during play.

A better approach is to measure the map directly.

Static and dynamic points of interest

Tactical value comes from two kinds of features:

• static features exist in the map itself
• dynamic features appear because of the current battle state

Static features include cliffs, water, walls, edges of the map, natural chokepoints, and built structures.

Dynamic features include the front line, a retreat route, a newly opened flank, or a region that has become dangerous after unit movement.

The difference matters because a tactically useful location is not useful in isolation. It is useful relative to the current game state.

RTS examples: controlling movement

In an RTS, terrain usually matters because it controls movement and commitment.

A chokepoint forces units through a narrow route. That gives defenders a chance to concentrate force. A cliff or wall changes the paths an army can take. An ambush site gives one side a timing or positioning advantage. A flanking route breaks a straight-line engagement by creating another angle of attack.

The common pattern is control. Good terrain makes enemy movement more predictable.

FPS examples: controlling visibility

In a shooter, terrain usually matters because it changes what can be seen and what can be hit.

Cover points reduce exposure. Sniper positions trade safety for sightlines. Escape routes matter because survival often depends on leaving a bad position quickly. Dark areas and low-visibility paths can reduce risk during movement.

A good spot in an FPS is rarely just “high ground.” It usually combines protection, visibility, and a way out.

What makes a location tactically useful

Across both genres, the same properties come up repeatedly:

• control
• visibility
• protection
• accessibility
• cost

A tactically useful place does one or more of these things well. It forces movement, improves line of sight, reduces exposure, or creates an efficient route.

That is a more reliable model than treating “high ground” as a universal answer.

Practical takeaway

Tactical terrain analysis is not about memorizing special map locations.

It is about identifying which parts of the map change the odds of a fight.

Once that idea is clear, the next step is easier: store visibility and exposure in the navigation data so the AI can use it directly.

That is where waypoint reasoning starts to become tactical reasoning.

If each node knows what it can see, the graph can answer tactical questions, not just pathfinding questions.

Visibility is the tactical signal

Visibility tells you several things at once:

• whether a position is exposed
• whether it provides cover
• whether it is good for attacking from
• whether a route is safe to travel
• whether the position is likely to attract return fire

That makes visibility one of the strongest signals in tactical AI. It is cheap to reason about and rich in meaning.

Precomputing node visibility

The standard approach is to preprocess the terrain and store visibility information on waypoint nodes.

Each node can keep a compact record of which other nodes it can see. Bit strings work well for that representation because set operations are fast:

• and for overlap
• or for union
• not for exclusion

With that data, the AI can compare whole groups of nodes instead of doing expensive reasoning during combat.

Safe and dangerous nodes

Once visibility is stored, nodes can be scored by risk.

A node that is visible to enemies is more dangerous. A hidden node is usually safer. The useful part is not a strict safe/unsafe label. The useful part is a cost model.

That allows the pathfinder to do something practical:

• prefer low-exposure paths
• penalize dangerous nodes
• still allow risky movement when needed

That is much better than pretending exposed ground is always forbidden.

Attack positioning

The same data can be used to choose attack positions.

A good attack node is not just visible to the target. It is also hidden from other threats when possible.

A simple rule looks like this:

1. find nodes visible to the target
2. remove nodes visible to other enemies
3. keep the remaining nodes as safer attack positions

This is a strong pattern because it turns a fuzzy tactical idea into a filter.

Flanking and sneaking

Flanking is not a special case. It is a visibility problem.

A flank route is useful because it changes who can see whom. Sneaking works the same way: stay out of sight for as long as possible, and arrive from a direction that creates advantage.

That is why visibility data belongs in the navigation layer.

Practical takeaway

Waypoint graphs become tactical when they stop describing only movement and start describing exposure.

That shift makes the AI better at choosing routes, selecting attack positions, and avoiding unnecessary risk.

The next layer is broader than visibility. It measures pressure across the whole map.

Influence maps tell you how much pressure exists there.

That difference matters. A position can be visible without being dangerous, and dangerous without being fully visible. Influence maps help estimate the shape of the fight instead of only the geometry of the map.

What an influence map is

An influence map is a grid layered over the terrain. Each cell stores a value that represents power, danger, control, or importance.

The value usually comes from units or other sources, and it falls off with distance. Nearby cells matter more than distant ones.

That gives the AI a smooth tactical field to reason about.

What the map helps with

Influence maps are useful when the AI needs to answer questions like:

• where is the strongest enemy presence?
• where is the weakest point in the line?
• what route avoids the center of the fight?
• where is a good flank?
• where is the front of the battle?

The map does not give perfect answers. It gives a good estimate. That is often enough for decision-making.

Combining multiple sources

Influence is rarely coming from one source.

Friendly units, enemy units, objectives, and terrain features can all contribute. The final map is a combination of those signals.

That is what makes the technique useful in both combat and non-combat systems.

The same idea can model crime, pollution, police coverage, fire coverage, or traffic pressure. Any system with spatial force or pressure can use the pattern.

Why it is useful

Influence maps sit between exact pathfinding and high-level strategy.

Pathfinding finds a route. Influence maps help decide whether that route is smart.

That makes them a strong middle layer for tactical AI.

Practical takeaway

Use influence maps when the AI needs a broad read on the battlefield.

They are not a substitute for line-of-sight checks or pathfinding. They are a way to estimate where the fight is strong, weak, safe, or dangerous.

The next step is to store more than one tactical signal at once.

A layered spatial database is easier to debug because each layer answers one question.

Why layers matter

A tactical AI usually needs more than one kind of spatial information.

One layer can describe visibility. Another can describe cover. Another can describe occupancy or line of fire. Keeping those signals separate makes the system easier to reason about.

That is the main idea behind the spatial database in the lecture: represent the map as a stack of tactical views.

Common layers

The slides describe several useful layers:

• visibility
• openness
• cover
• area occupancy
• line of fire
• light level
• area search

Each layer answers a specific question.

• visibility: how exposed is this area?
• openness: how much room is available?
• cover: can an AI survive here?
• occupancy: how crowded is the area?
• line of fire: where are weapons aimed?
• light level: is the area bright or dark?
• area search: has the area already been checked?

That separation is important. It keeps the model inspectable.

Combining the layers

The lecture uses a combat desirability layer as an example.

That layer combines signals such as openness, cover, and occupancy into one score.

The exact formula matters less than the design principle: multiple tactical signals should be combined carefully, not smashed into one arbitrary number.

The geometric mean is a good warning here. It prevents one good factor from hiding several bad ones.

Why this is better than a black box

If the AI chooses a bad position, a layered system makes it possible to find out why.

Was the area too exposed?

Was it crowded?

Was there too much line-of-fire pressure?

A single hidden score cannot answer those questions. Separate layers can.

That is valuable for debugging and for balancing the AI.

Practical takeaway

Spatial databases make tactical AI easier to extend because each layer stays focused on one signal.

That makes the system more readable, easier to debug, and less likely to collapse into one opaque heuristic.

The final step is to turn this into a simple implementation plan.

The first version does not need to model everything. It needs to answer one or two useful questions clearly.

Start with one signal

The first step is to pick one tactical signal that is easy to measure.

Good candidates are:

• visibility
• cover
• a small penalty for exposed paths

The point is not completeness. The point is to get a result that changes behavior in a useful way.

Add a second layer later

Once the first signal works, add a second one.

That might be:

• occupancy
• danger
• line of fire
• influence

Each new layer should earn its place. If a layer does not improve the decision, it should stay out.

That discipline keeps the system understandable.

Keep the score explainable

A tactical score is only useful if it can be explained.

When the AI chooses a spot, the system should be able to say why:

• this route is exposed
• this area is crowded
• this position is visible
• this flank is under pressure

If the reason is not visible, debugging becomes guesswork.

What to avoid

The main mistake is trying to build a perfect tactical brain on day one.

That usually leads to a system that is hard to tune and hard to trust.

A smaller system with one clear benefit is better than a large system nobody understands.

A practical shape for version one

A useful first version usually looks like this:

1. a small waypoint graph or grid
2. one tactical score
3. clear debug output
4. one or two simple overlays
5. a gradual path to more layers

That is enough to prove the idea without overbuilding it.

Practical takeaway

Tactical AI works best when it grows in layers.

Start with one reliable signal. Add another only when it improves the model. Keep the decision explainable at every stage.

That is how a tactical system stays useful instead of turning into noise.

Flyweight is about memory and bandwidth. When ten thousand objects carry the same mesh reference, the same stat table, and the same sound list, that data should exist once and be shared.

Object pooling is about lifetime churn. When a game spawns and destroys hundreds of short-lived objects per second, such as bullets, hit sparks, damage numbers, and audio sources, the cost is in creating and tearing them down, not in what they hold. A pool keeps a set of instances alive and hands them out again.

Both patterns are old, and both are covered in Robert Nystrom’s Game Programming Patterns. This post covers how each one maps onto Unity and C#, where each one fails, and how to combine them so a pooled bullet carries almost no data of its own.

Two different questions

A quick way to tell which pattern applies is to ask what is expensive.

If the problem is “there are too many copies of the same data,” the answer is a flyweight. Symptoms: memory grows linearly with object count, inspectors show the same arrays duplicated across prefab instances, or a draw-call count climbs because every object looks like a unique case to the renderer.

If the problem is “objects keep being born and dying,” the answer is a pool. Symptoms: frame-time spikes during heavy combat, Instantiate and Destroy near the top of the profiler, garbage collection hitches in a profiler capture, or a mobile build that stutters when an effect fires.

Some systems have both problems. A bullet-hell shooter has thousands of bullets that all share a handful of bullet types, and every bullet lives for under two seconds. That is why the patterns pair well, and why it matters to keep them separate in the design. A flyweight that is also doing pool bookkeeping becomes hard to reason about.

Flyweight: split intrinsic from extrinsic state

The classic definition splits an object’s data in two.

Intrinsic state is shared and does not change per instance: the mesh, the base stats, the attack list, the hit sound. Extrinsic state is specific to one instance: its position, current health, cooldown timer, and target.

Nystrom’s example is a forest of trees. Each tree has a mesh, bark texture, and leaf texture (shared), plus a position, height, and tint (unique). Pulling the shared part into a TreeModel means the mesh exists once in memory rather than a thousand times, and graphics APIs that support instanced rendering can draw the whole forest from one model plus a list of per-instance parameters. He points out that this may be the only Gang of Four pattern with direct hardware support.

In Unity, the natural vehicle for intrinsic state is a ScriptableObject. It is an asset, so every object that references it points at the same instance:

using UnityEngine;

[CreateAssetMenu(menuName = "Game/Enemy Definition")]
public sealed class EnemyDefinition : ScriptableObject
{
    [SerializeField] private int maxHealth = 100;
    [SerializeField] private float moveSpeed = 3.5f;
    [SerializeField] private float attackRange = 1.8f;
    [SerializeField] private AudioClip hitSound;
    [SerializeField] private AnimationCurve damageFalloff;

    public int MaxHealth => maxHealth;
    public float MoveSpeed => moveSpeed;
    public float AttackRange => attackRange;
    public AudioClip HitSound => hitSound;
    public AnimationCurve DamageFalloff => damageFalloff;
}

The runtime component keeps only what changes:

public sealed class Enemy : MonoBehaviour
{
    [SerializeField] private EnemyDefinition definition;

    private int health;
    private float attackCooldown;

    private void OnEnable()
    {
        health = definition.MaxHealth;
        attackCooldown = 0f;
    }

    public void TakeDamage(int amount)
    {
        health -= amount;
        if (health <= 0)
            Die();
    }

    private void Die() { /* ... */ }
}

Two properties make this a flyweight rather than a loose bag of settings. The definition is read-only at runtime (private fields, getters only), and the instance never copies definition values into its own fields except for state that must diverge, like current health.

What the savings look like

The saving depends on what the shared data is. A few floats and ints are trivial either way, and a ScriptableObject reference is itself a pointer in every instance. The real gains come from heavy shared payloads: AnimationCurve objects, lists of ability descriptions, localization tables, large config arrays, and anything serialized inline on a prefab.

That last case is easy to miss. If a prefab has a serialized List<AbilityData> on its component, every instance of that prefab carries its own managed copy of the list when instantiated. Move the list into a ScriptableObject and reference it, and the copies collapse into one. Measure first. The Memory Profiler package can show managed object counts and sizes per type, which is a more reliable guide than guessing from the inspector.

Rendering is the other half

Unity applies the same idea to materials and meshes, and there is a classic trap hiding in it.

Reading renderer.material returns an instance copy of the material, creating one if the renderer does not already have its own. Assign a tint through it on a thousand objects and there are a thousand materials, which defeats batching and leaks memory if they are never destroyed. renderer.sharedMaterial returns the shared asset, but writing a property through it changes every object that uses the material.

The flyweight-friendly path is a MaterialPropertyBlock, which carries per-instance overrides without cloning the material:

public sealed class TintedRenderer : MonoBehaviour
{
    private static readonly int ColorId = Shader.PropertyToID("_BaseColor");

    [SerializeField] private Renderer target;
    private MaterialPropertyBlock block;

    public void SetTint(Color color)
    {
        block ??= new MaterialPropertyBlock();
        target.GetPropertyBlock(block);
        block.SetColor(ColorId, color);
        target.SetPropertyBlock(block);
    }
}

This is the same split as the forest: one shared material and mesh, plus a small per-instance override. Whether property blocks batch well depends on the render pipeline in use. In pipelines that use the SRP Batcher, per-renderer property blocks can interfere with SRP Batcher compatibility, so check the Frame Debugger before assuming it helped. GPU instancing and the SRP Batcher are different mechanisms with different rules, and the right choice is a rendering-specific question that deserves its own measurement.

The shared-mutation bug

A flyweight only works while the shared part stays immutable. The most common failure is gameplay code that writes into the definition:

// Bug if MoveSpeed were a writable field: every goblin just got faster.
definition.MoveSpeed *= 1.2f; // does not compile with the read-only API above

The read-only properties above are deliberate. Without them, a buff applied to one enemy rewrites the asset in memory, affects every enemy using that definition, and in the editor it can also persist into the saved asset after play mode ends. Buffs belong in extrinsic state: a modifier list on the instance, applied on top of the definition’s base values.

public float CurrentMoveSpeed => definition.MoveSpeed * speedMultiplier;

Object pooling: reuse the instance, not just the data

A flyweight reduces what each object holds. A pool reduces how often objects are created at all.

Nystrom’s definition is a fixed collection of reusable objects, each with an “in use” flag. Ask the pool for one, and it finds a free object and marks it live. When the object is no longer needed, it goes back to “not in use.” His motivating examples are particle systems and fragmentation on constrained hardware, where a heap full of small holes can fail an allocation even when plenty of total memory is free.

Unity’s situation is a little different from a console-era C++ heap. Fragmentation of the managed heap is real but rarely the first complaint. The usual costs are:

• Instantiate has to clone a hierarchy, run Awake and OnEnable on every component, and register everything with engine systems.
• Destroy is deferred to the end of the frame and tears the same machinery down.
• Any managed allocation created along the way (closures, lists, strings, per-instance arrays) feeds the garbage collector, which can cause a hitch when it runs.

Pooling swaps most of that work for activating and deactivating something that already exists. The cost is memory held in reserve and the responsibility to reset state correctly. Neither is free, so both need to be weighed against a measured problem.

The built-in pool

Since Unity 2021.1, UnityEngine.Pool ships an ObjectPool<T>, so a hand-rolled pool is rarely necessary for GameObjects. The documentation describes it as a stack-based pool whose constructor takes delegates for creation, taking from the pool, returning to the pool, and destroying, plus a default capacity, a maximum size, and an optional collection check that catches double releases.

using UnityEngine;
using UnityEngine.Pool;

public sealed class ProjectilePool : MonoBehaviour
{
    [SerializeField] private Projectile prefab;
    [SerializeField] private int prewarmCount = 32;
    [SerializeField] private int maxRetained = 128;

    private ObjectPool<Projectile> pool;

    private void Awake()
    {
        pool = new ObjectPool<Projectile>(
            createFunc: CreateProjectile,
            actionOnGet: p => p.gameObject.SetActive(true),
            actionOnRelease: p => p.gameObject.SetActive(false),
            actionOnDestroy: p => Destroy(p.gameObject),
            collectionCheck: true,
            defaultCapacity: prewarmCount,
            maxSize: maxRetained);

        Prewarm();
    }

    private Projectile CreateProjectile()
    {
        Projectile instance = Instantiate(prefab, transform);
        instance.gameObject.SetActive(false);
        return instance;
    }

    private void Prewarm()
    {
        var warm = new Projectile[prewarmCount];
        for (int i = 0; i < warm.Length; i++)
            warm[i] = pool.Get();
        for (int i = 0; i < warm.Length; i++)
            pool.Release(warm[i]);
    }

    public Projectile Fire(ProjectileDefinition def, Vector3 origin, Vector3 direction)
    {
        Projectile p = pool.Get();
        p.Launch(def, origin, direction, pool);
        return p;
    }
}

Several details here are easy to get wrong.

defaultCapacity sizes the internal collection. It does not create objects. Without the Prewarm loop, the first burst of fire still instantiates on demand, which is exactly the hitch the pool was meant to prevent.

maxSize limits how many instances the pool retains, not how many can be active. If more than maxSize objects are released, the extras go through actionOnDestroy. Calling Get on an empty pool always creates a new instance. If a hard cap on active objects matters (a rule such as “never more than 64 bullets on screen”), it has to be enforced outside the pool.

collectionCheck: true throws on a double release. The check amounts to a linear search of the pooled items, so on a pool that retains hundreds of objects it is not free. Treat it as a development aid and confirm with a profile before leaving it on in a hot path.

The Unity documentation also notes that ObjectPool<T> is not safe to call from background threads and that its objects are stored in a stack-like collection, so there is no guarantee about contiguity in memory. The pool saves allocation work, not cache misses.

The pooled object owns its return trip

The projectile needs a way back to the pool. Passing the pool in at launch avoids a global lookup:

using UnityEngine;
using UnityEngine.Pool;

public sealed class Projectile : MonoBehaviour
{
    [SerializeField] private Rigidbody body;
    [SerializeField] private TrailRenderer trail;

    private IObjectPool<Projectile> owner;
    private ProjectileDefinition definition;
    private float timeLeft;
    private bool released;

    public void Launch(
        ProjectileDefinition def,
        Vector3 origin,
        Vector3 direction,
        IObjectPool<Projectile> pool)
    {
        definition = def;
        owner = pool;
        timeLeft = def.Lifetime;
        released = false;

        transform.SetPositionAndRotation(origin, Quaternion.LookRotation(direction));
        body.linearVelocity = direction.normalized * def.Speed; // `velocity` before Unity 6
        body.angularVelocity = Vector3.zero;
        trail.Clear();
    }

    private void Update()
    {
        timeLeft -= Time.deltaTime;
        if (timeLeft <= 0f)
            Despawn();
    }

    private void OnTriggerEnter(Collider other)
    {
        // apply damage using definition.Damage ...
        Despawn();
    }

    private void Despawn()
    {
        if (released)
            return; // timeout and hit can land in the same frame
        released = true;
        owner.Release(this);
    }
}

The released flag matters. A projectile can time out and hit something in the same frame, and releasing twice puts the same object in the pool twice. Then two callers get the same instance, and the symptoms are strange: a bullet teleports mid-flight, or two enemies get hit by one shot. With collectionCheck on, the second release throws instead, which is the better failure.

The reset checklist is the real cost

A pooled object is a used object. It remembers everything its previous life did, so every bug in a pool is some form of stale state.

The things worth checking each time something goes back in:

• Physics state. Velocity, angular velocity, and any forces applied. A reused rigidbody that keeps its last velocity launches in the wrong direction.
• Trails and particles. TrailRenderer.Clear() removes the streak between the old position and the new one. Particle systems need Stop or Clear before reuse, or the previous burst replays.
• Event subscriptions. A pooled object that subscribes in Launch and never unsubscribes responds to events for owners it no longer has. Pair every subscribe with an unsubscribe in the release path.
• Running coroutines and async work. A coroutine started in the last life continues in the next one unless it is stopped. Cancellation tokens tied to the object’s active lifetime handle this more reliably than flags.
• Timers and cooldowns. Reset all of them on spawn, not just the obvious one.
• Parenting and scale. Something attached to a moving parent during its last life may still be a child.
• Visual state. Tint overrides, animation state, and enabled sub-objects (a charged-shot glow that was on when the object died).

The cleanest approach is to make initialization a single method that sets everything, as Launch does above, rather than scattering resets across OnEnable, OnDisable, and the caller. If a new field gets added to the component, there is exactly one place to update.

Using OnEnable and OnDisable as the lifecycle hooks is tempting because SetActive triggers them. It works, but it hides ordering: OnEnable runs before Launch supplies the definition. Anything that needs the definition has to wait for Launch.

A handle-based pool for data that is not a GameObject

GameObject pooling is the common case, but the pattern is more general, and a pure data pool is often the better design for very large counts. Ten thousand bullets rarely need ten thousand GameObjects. They need positions, velocities, and a lifetime, which can live in arrays and be rendered by instancing.

That design has a hazard. If a system holds a plain index into the array, and the slot is released and reused, the old index now silently refers to a different bullet. The standard fix is a generation counter: each slot has a number that increments on release, and the handle stores both the index and the generation it was issued with.

using UnityEngine;

public readonly struct BulletHandle
{
    public readonly int Index;
    public readonly int Generation;

    public BulletHandle(int index, int generation)
    {
        Index = index;
        Generation = generation;
    }
}

public sealed class BulletPool
{
    private readonly BulletDefinition[] definitions;
    private readonly Vector3[] positions;
    private readonly Vector3[] velocities;
    private readonly float[] timeLeft;
    private readonly int[] generations;
    private readonly bool[] alive;
    private readonly int[] freeSlots;
    private int freeCount;

    public BulletPool(int capacity)
    {
        definitions = new BulletDefinition[capacity];
        positions = new Vector3[capacity];
        velocities = new Vector3[capacity];
        timeLeft = new float[capacity];
        generations = new int[capacity];
        alive = new bool[capacity];
        freeSlots = new int[capacity];

        for (int i = 0; i < capacity; i++)
        {
            generations[i] = 1; // 0 is reserved so default(BulletHandle) is never valid
            freeSlots[i] = capacity - 1 - i;
        }
        freeCount = capacity;
    }

    public bool TryFire(
        BulletDefinition def,
        Vector3 origin,
        Vector3 direction,
        out BulletHandle handle)
    {
        if (freeCount == 0)
        {
            handle = default;
            return false; // caller decides: drop the shot, or recycle the oldest
        }

        int i = freeSlots[--freeCount];
        definitions[i] = def;
        positions[i] = origin;
        velocities[i] = direction.normalized * def.Speed;
        timeLeft[i] = def.Lifetime;
        alive[i] = true;

        handle = new BulletHandle(i, generations[i]);
        return true;
    }

    public bool IsAlive(BulletHandle h) =>
        h.Index >= 0 && h.Index < alive.Length &&
        alive[h.Index] && generations[h.Index] == h.Generation;

    public void Tick(float dt)
    {
        for (int i = 0; i < alive.Length; i++)
        {
            if (!alive[i])
                continue;

            positions[i] += velocities[i] * dt;
            timeLeft[i] -= dt;
            if (timeLeft[i] <= 0f)
                Release(i);
        }
    }

    private void Release(int i)
    {
        alive[i] = false;
        definitions[i] = null;
        generations[i]++;
        freeSlots[freeCount++] = i;
    }
}

This pool allocates once in the constructor and never again. TryFire returns false when full, which forces the caller to pick one of the overflow strategies Nystrom lists: size the pool so it never overflows, skip the new object, kill an existing one, or grow the pool. For cosmetic bullets, skipping is usually right. For a boss spawn, the pool must be sized so the question never comes up.

Notice what each slot stores: a reference to a shared BulletDefinition and four small pieces of per-bullet state. That is the combined design. The flyweight holds speed, damage, lifetime, mesh, and material. The pool holds a slot, a handle, and nothing else. Neither pattern had to be bent to make this work.

A short check is worth keeping beside code like this, because generation bugs are quiet:

var pool = new BulletPool(2);
var def = ScriptableObject.CreateInstance<BulletDefinition>();

pool.TryFire(def, Vector3.zero, Vector3.forward, out var first);
pool.Tick(def.Lifetime + 0.1f);                       // first expires, slot is freed
pool.TryFire(def, Vector3.zero, Vector3.forward, out var second);

Debug.Assert(!pool.IsAlive(first));   // stale handle must not alias the reused slot
Debug.Assert(pool.IsAlive(second));

If IsAlive(first) ever returns true after the slot is reused, the generation logic is broken, and the symptom in-game would be damage applied to the wrong bullet.

Sizing and overflow

Pool size is a gameplay decision wearing an engineering costume.

Too small, and shots silently vanish or objects are created mid-fight, which is the hitch the pool existed to prevent. Too large, and the memory sits idle, which matters on mobile and console budgets. Nystrom’s advice is blunt: a crash makes an undersized pool obvious, so also watch for oversized ones, because they cost memory that something else could use.

A practical approach:

1. Run a worst-case scenario (the heaviest encounter, the highest fire rate, all upgrades active).
2. Record the peak number of simultaneously active objects. Log it from the pool during play, which costs one integer comparison per spawn.
3. Set the prewarm count near typical peak and the retained cap near the worst-case peak plus a small margin.
4. Keep the logging in development builds so later balance changes that raise the peak get noticed.

Separate pools per object type also help. One shared pool for “effects” lets a flood of sparks starve a more important effect. Partitioning memory by purpose is a feature, not a limitation.

Common mistakes

Pooling without profiling. If a prefab spawns a few times per minute, a pool adds code, memory, and reset bugs for no measurable gain. Capture a profile with the problem present, confirm that Instantiate, Destroy, or GC allocation is the cost, and then pool the specific objects responsible.

Forgetting that SetActive(false) still costs memory. Pooled objects stay resident. A pool of two hundred complex enemy prefabs holds all of their components, meshes in use, and audio sources even when none are on screen.

Resetting in the wrong place. If reset logic is split among the pool, the caller, and several components, one will be missed. Centralize it.

Mutating the flyweight. Anything writing to a shared definition at runtime changes every object that uses it. Keep definitions read-only and layer modifiers on the instance.

Holding raw references to pooled objects. A system that stores a Projectile reference after the projectile returned to the pool may now be talking to a different bullet. Use handles with generations, or clear references in the release path.

Treating a pool as a fix for allocation inside the object. Pooling a Projectile does nothing if its Update allocates a list or a closure every frame. Fix the per-frame allocation separately.

Using both patterns where one is enough. A pool of identical, tiny objects does not need a definition asset. A set of long-lived, unique enemies does not need a pool. Match the pattern to the cost that exists.

When to skip both

Flyweight is not worth the indirection when there are only a few instances. Ten enemies with their own copies of a stat block cost nothing that matters, and a per-instance setup is easier to tweak in the inspector.

Pooling is not worth the reset burden for objects that are expensive but rare, like a boss, a level transition, or a UI screen opened a few times a session. Those costs are better hidden behind a loading screen or spread across frames with async loading than paid for in permanent memory.

There is also a middle ground for arrays and lists. ArrayPool<T> from System.Buffers and the collection pools in UnityEngine.Pool (such as ListPool<T>) cover temporary buffers, so code that builds a list every frame can borrow and return one without writing a custom pool.

Practical takeaway

Treat the two patterns as answers to two questions. If many objects carry identical data, move that data into a read-only shared definition and keep only per-instance state on the object. If many objects are created and destroyed quickly, keep a bounded set of them alive and recycle them through a single reset path.

When using Unity’s ObjectPool<T>, prewarm explicitly, enforce the active-object cap outside the pool, guard against double release, and decide up front what happens when the pool runs dry. For data-oriented pools, issue handles with a generation counter so stale references fail loudly instead of pointing at a stranger.

Then measure. Both patterns trade memory and complexity for speed, and that trade is only worth making when a profile shows the cost it removes.

References

• Robert Nystrom, Game Programming Patterns, Flyweight — the forest example, the intrinsic/extrinsic split, and the note about hardware instancing.
• Robert Nystrom, Game Programming Patterns, Object Pool — fragmentation, fixed-size trade-offs, overflow strategies, and the warning that reused objects are not cleared for you.
• Unity Scripting API, ObjectPool<T> — constructor parameters, maxSize behavior, collection checks, and the thread-safety note.
• Unity Scripting API, MaterialPropertyBlock — per-renderer overrides without cloning materials.
• Unity Manual, ScriptableObject — using assets to hold shared data and reduce per-instance copies.

It sounds abstract until you have lived it. A character-select screen has a portrait list, a preview model, a stat panel, a ready button, a team summary, and a lobby connection. Clicking a portrait changes the preview. Changing the preview changes the stats. The ready button depends on the selection being valid. The lobby needs to know when everyone is ready. If every widget holds a reference to every other widget, adding a single new panel means threading one more dependency through the whole pile.

The mediator offers a different shape. Colleagues do not know about each other. They talk to one object in the middle, and that object decides who else needs to hear about it.

That is the whole pattern in a sentence. The difficulty, as usual, is deciding where the middle object should live and how much it is allowed to know.

The shape of the pattern

A mediator has two kinds of participant.

The colleagues are the components that need to coordinate. They do the actual work: rendering a portrait, computing stats, applying a preview, sending a lobby message. Each colleague knows about the mediator, but not about the other colleagues.

The mediator knows about all of its colleagues and owns the rules for how they coordinate. When a colleague reports a change, the mediator decides what that change means and tells the affected colleagues.

In C#, a minimal version looks like this:

public interface IMediator
{
    void Notify(object sender, string message);
}

public sealed class SelectionMediator : IMediator
{
    private PortraitList? portraits;
    private StatPanel? stats;
    private PreviewModel? preview;
    private ReadyButton? ready;

    public void Register(object component)
    {
        switch (component)
        {
            case PortraitList p: portraits = p; break;
            case StatPanel s: stats = s; break;
            case PreviewModel m: preview = m; break;
            case ReadyButton r: ready = r; break;
        }
    }

    public void Notify(object sender, string message)
    {
        if (sender == portraits && message == "selected")
        {
            preview?.Show(portraits!.Current);
            stats?.Refresh(portraits.Current);
            ready?.SetEnabled(portraits.Current != null);
        }
        else if (sender == ready && message == "ready")
        {
            // tell the lobby, not the other widgets
        }
    }
}

The colleagues call the mediator when something happens, and the mediator is the only object that knows the full choreography.

Notice what is missing: no colleague holds a reference to another colleague. The portrait list does not know the stat panel exists. The ready button does not reach into the preview model. That is the payoff.

The cost is equally visible: the mediator knows a lot. That is the tradeoff the pattern asks you to accept on purpose, and most of the discipline around mediators is about keeping that knowledge contained.

Mediator is not an event bus, and not just observer

This is the distinction that causes the most confusion, because all three patterns are about communication without direct references.

Observer is one-to-many. A subject keeps a list of listeners and notifies them without knowing what they do. The subject is reusable because it does not care about its listeners.

An event bus is a global broadcast channel. Producers publish, consumers subscribe, and neither side knows the other. The bus is usually process-wide and generic.

A mediator is a scoped, opinionated object. It does know its colleagues, it does understand the feature, and it makes decisions about the flow. It is closer to a small coordinator or a mini-controller than to a dumb pipe.

The practical difference shows up in where the logic lives. With an event bus, the coordination rules are scattered across the subscribers. When a selection changes, the stat panel subscribes to SelectionChanged and refreshes, the preview subscribes and renders, the ready button subscribes and revalidates. Each listener knows its own slice, and nobody knows the whole flow. That is often what you want for fire-and-forget notifications.

With a mediator, the flow lives in one place. SelectionChanged becomes mediator.Notify(this, "selected"), and the mediator is the single object that knows “a selection change means update preview, then stats, then ready state.” If the rules change, you edit the mediator, not six scattered listeners.

Neither is universally better. Event buses scale to many-to-many communication and let systems stay ignorant of each other. Mediators scale to a bounded group that has a real, deliberate workflow. If your “mediator” has forty colleagues and a stringly-typed message protocol, you have built an event bus with extra steps and should probably just use the bus.

A concrete example: turn-based combat

Turn flow is a natural mediator candidate because it has a real sequence with several actors.

A tactics battle needs to coordinate the turn manager, the unit selection input, the action menu, the movement validator, the attack resolver, and the HUD. If the turn manager holds references to all of those, and the HUD holds references back to the turn manager, you get a cycle that is hard to reason about and harder to test.

A BattleMediator can own the sequence:

public sealed class BattleMediator
{
    private readonly TurnManager turns;
    private readonly UnitSelection selection;
    private readonly ActionMenu menu;
    private readonly MoveValidator moveValidator;
    private readonly AttackResolver attackResolver;
    private readonly BattleHud hud;

    public BattleMediator(
        TurnManager turns,
        UnitSelection selection,
        ActionMenu menu,
        MoveValidator moveValidator,
        AttackResolver attackResolver,
        BattleHud hud)
    {
        this.turns = turns;
        this.selection = selection;
        this.menu = menu;
        this.moveValidator = moveValidator;
        this.attackResolver = attackResolver;
        this.hud = hud;
    }

    public void OnUnitSelected(UnitId unit)
    {
        menu.ShowFor(unit);
        hud.Highlight(unit);
        hud.ShowMoveRange(moveValidator.RangeFor(unit));
    }

    public void OnActionChosen(IAction action)
    {
        if (action is MoveAction move)
        {
            menu.Hide();
            hud.ShowMoveTargets(moveValidator.TargetsFor(selection.Current, move));
        }
        else if (action is AttackAction attack)
        {
            menu.Hide();
            hud.ShowAttackTargets(attackResolver.TargetsFor(selection.Current, attack));
        }
    }

    public void OnTargetConfirmed(TargetId target)
    {
        var result = attackResolver.Resolve(selection.Current, selection.Action, target);
        hud.ShowResult(result);
        turns.Advance();
    }
}

The combat pieces stay focused on their own job. The mediator holds the script of the turn. When a new feature lands — an assist action, a reaction trigger, an undo step — it is one more branch in a class that is already the designated owner of that flow.

That is the healthy version. The unhealthy version is when BattleMediator also starts managing the inventory, the quest log, the save system, and the camera, because it happens to be convenient to route everything through one object. The scope line is the difference between a mediator and a god object.

Scope is the whole discipline

A mediator should own one feature, one screen, or one bounded workflow. The selection mediator owns selection. The battle mediator owns the battle turn. The settings mediator owns the settings screen.

The moment a mediator starts coordinating across two unrelated features, it is accumulating the same global knowledge the pattern was meant to avoid. It has not removed the web; it has rolled the web into a ball and hidden it behind a name.

A useful rule of thumb: if you can describe what the mediator coordinates in one short sentence, it is probably scoped well. “Coordinates the character-select screen.” “Coordinates the battle turn.” “Coordinates the in-game HUD and pause menu.” If the description needs a paragraph and three caveats, the mediator is doing too much and should be split along the features it touches.

Splitting is usually cheap. A LobbyMediator can talk to a SelectionMediator through a narrow interface, the same way a colleague talks to its own mediator. Mediators can be colleagues of a higher-level mediator. The pattern composes, and composing is how you keep any single object from swallowing the project.

Keep messages typed and small

The stringly-typed Notify(sender, "selected") shape is the classic textbook version, and it works for small examples. It is also a magnet for typos and for the “who sends which string” scavenger hunt that makes mediator code annoying to debug.

In real game code I usually prefer typed messages. Instead of one Notify method with a string, give the mediator explicit methods like OnUnitSelected and OnTargetConfirmed above, or route a small typed event object through it.

public readonly record struct SelectionChanged(UnitId? Unit);

public sealed class SelectionMediator
{
    public void Handle(SelectionChanged changed)
    {
        preview?.Show(changed.Unit);
        stats?.Refresh(changed.Unit);
        ready?.SetEnabled(changed.Unit is not null);
    }
}

Typed methods or records buy you compiler-checked wiring and make the flow greppable. The strings buy you nothing except a habit that breaks the first time you rename a message and miss a sender.

The tradeoff is that typed mediators are less generic. A single IMediator with one Notify method can be reused across many features; a typed mediator is written per feature. For a game, the per-feature cost is usually worth it, because game features are bespoke anyway and the coordination rules rarely look identical between them.

Do not build a generic reusable mediator framework before you have at least three concrete mediators that are actually painful to write. Generic message-broker infrastructure is a framework problem, and most game teams do not have it. They have three screens that need a coordinator, which is a much smaller problem.

Wiring it in Unity

There are two common ways to give a mediator its colleagues in Unity, and they map to two different stages of a project.

The simplest is a MonoBehaviour mediator that grabs references in the scene. A character-select screen is a concrete scene layout, so a SelectionScreenMediator : MonoBehaviour with [SerializeField] references to the widgets can be wired in the Inspector and left alone.

public sealed class SelectionScreenMediator : MonoBehaviour
{
    [SerializeField] private PortraitList portraits;
    [SerializeField] private StatPanel stats;
    [SerializeField] private PreviewModel preview;
    [SerializeField] private ReadyButton ready;
    [SerializeField] private LobbyClient lobby;

    public void OnPortraitSelected(UnitId unit)
    {
        preview.Show(unit);
        stats.Refresh(unit);
        ready.SetEnabled(unit != null);
    }

    public void OnReadyPressed()
    {
        if (portraits.Current is not UnitId unit) return;
        lobby.SendReady(unit);
    }
}

This is fine for a feature that lives in one scene and is authored by hand. The Inspector wiring is explicit, and the mediator is where a designer or another programmer expects to find the screen logic.

The second way is to inject a plain C# mediator with a composition root or a small DI container. This is better for gameplay flows that are created at runtime and tested without a scene: a battle mediator, a match-flow coordinator, a tutorial script. The mediator becomes an ordinary object you can construct in a test with fake colleagues.

var mediator = new BattleMediator(
    new TurnManager(),
    new UnitSelection(),
    new ActionMenu(fakeInput),
    new MoveValidator(grid),
    new AttackResolver(combatRules),
    new BattleHud(fakeView));

mediator.OnUnitSelected(unit);
// assert the fake view received a highlight call

The pattern does not force either choice. Keep the mediation logic in plain C# when you can, because it is the kind of flow logic that benefits from being testable without booting Unity. Wrap it in a MonoBehaviour only where the scene is the natural owner of the wiring.

Common mistakes

The first mistake is treating mediator as a default. Most communication in a game does not need a middleman. A direct call from the player controller to the audio manager is fine. A plain event for “player died” is fine. Reach for a mediator when there is a real multi-step flow with several actors, not because you feel like the architecture should have one.

The second mistake is letting the mediator grow until it knows everything. A mediator that coordinates selection, combat, quests, saves, and settings is no longer a coordinator; it is the object you were trying to avoid. Scope it to one feature and split it when it bleeds over.

The third mistake is using strings for messages and then losing track of who sends what. Typed methods or small typed events keep the flow readable and compiler-checked. If you must use strings, at least define them as constants in one place and document who sends each one.

The fourth mistake is making the mediator do the colleagues’ work. The mediator routes and sequences. It should not also compute damage, render portraits, or validate movement. If the mediator contains the feature’s actual logic rather than its choreography, the responsibilities have blurred and you should push the work back into the colleague that owns it.

The fifth mistake is trying to make one generic mediator interface cover every feature before you have evidence that it pays off. Concrete, small, per-feature mediators are boring but they are also correct. A framework that generalizes over features you have not built yet is a bet on a problem you do not have.

When a mediator is the wrong tool

There are three signals that tell you to use something simpler.

If the coordination is one-way and the sender does not care who listens, use an event or an event bus. A mediator only earns its keep when the flow is deliberate and someone needs to own the whole script.

If the group of components is tiny and stable, direct references may be clearer than a middleman. Two widgets that always change together do not need a coordinator; they can just talk to each other. The pattern is for when the mesh grows and every new widget means several more edges.

If the logic is already owned by a state machine or a controller, a mediator can be redundant. A turn-based battle already has a turn state machine; the mediator might be the state machine with a new name. That is not necessarily wrong, but do not add a second object that does the same job.

The honest way to think about it: a mediator is a tool for keeping many-to-many coordination from becoming a many-to-many reference graph. If you do not have many-to-many coordination, you do not need it.

Practical takeaway

Use the mediator pattern when a bounded group of components has a real workflow that needs a single owner, and the alternative is every component holding references to every other.

Give the mediator explicit, typed methods or small typed events instead of string messages. Scope it to one feature and split it the moment it starts coordinating unrelated systems. Keep the actual work inside the colleagues and the choreography inside the mediator. In Unity, prefer a plain C# mediator for testable gameplay flows and a scene-bound MonoBehaviour only when the scene is the natural owner of the wiring.

The mediator is not a more powerful observer or a fancier event bus. It is a deliberate decision to centralize one small piece of coordination knowledge in exchange for removing the dependency web around it. Centralize the right piece, keep it small, and the pattern stays boring — which is exactly what you want from a middleman.

References

• Refactoring.Guru, Mediator — the classic originator/colleague framing and the comparison with observer.
• Robert Nystrom, Game Programming Patterns, Observer and Event Queue — useful adjacent reading for deciding between a mediator and a broadcast channel.
• Microsoft Learn, Events (C# Programming Guide) — the language-level events that often make a mediator unnecessary for simple one-way notifications.

That is an oversimplification, and it is worth being honest about why.

The service locator is a real tool with a real cost. It is not secretly good architecture, but it is also not a cardinal sin. The useful question is not “should I use a service locator” but “where does it belong, and what am I trading away when I use it.”

This post is a companion to the dependency injection articles already on this site. Those articles make the case for wiring dependencies at the edges. This one makes the case for the exception.

Pull versus push

Dependency injection and service location are two answers to the same question: how does an object get the collaborators it needs?

Dependency injection is a push model. Something outside the object hands it the dependencies, usually through a constructor or a setup method. The object never asks for anything. It just receives.

A service locator is a pull model. The object reaches into a shared registry and asks for what it wants, when it wants it.

// Push: the dependency arrives from outside.
public sealed class PlayerController
{
    private readonly IAudioService audio;

    public PlayerController(IAudioService audio)
    {
        this.audio = audio;
    }
}

// Pull: the object goes and fetches the dependency.
public sealed class PlayerController
{
    private IAudioService audio;

    public void Initialize()
    {
        audio = Services.Get<IAudioService>();
    }
}

Both end with the object holding a reference to IAudioService. The difference is who decided where that reference came from.

In the push version, the caller decides. In the pull version, the object decides, and the only thing it has to know is that a registry exists and contains audio.

The honest criticisms

The anti-service-locator arguments are correct. It helps to state them plainly instead of gesturing at them.

The dependency is hidden. Read a class that uses constructor injection and the signature tells you exactly what it needs. Read a class that pulls from a locator and you have to scan the body for every Services.Get<T>() call to build the same picture. The dependency graph still exists; it is just scattered inside method bodies.

Tests have to set up global state. A class that pulls from a static locator cannot be tested in isolation. Before the test runs, the registry has to be populated with the right fakes, and after it runs, the registry has to be cleaned up. That is global mutable state, and global mutable state makes tests order-dependent and easy to break.

Errors move to runtime. Constructor injection fails at construction time. If PlayerController needs audio and audio is missing, you find out when you try to build it. A locator can fail later, at some arbitrary point in a gameplay frame, when the object finally asks for a service that was never registered. The stack trace still points at the Get call, but the distance between the mistake and the failure has grown.

Coupling to the locator itself. Every class that calls Services.Get<T>() depends on the locator, not just on the service it wants. The locator becomes a hard-to-remove seam running through the whole codebase.

None of these are opinions. They are the mechanical consequences of hiding a dependency behind an ambient lookup. The next question is whether there are places where those costs are worth paying.

Why it is still here

If service location were purely harmful, it would have died out decades ago. It has not, because a few situations make the lookup genuinely the lesser evil.

Deep call chains. Sometimes a service has to travel through ten layers of objects before it reaches the one that uses it. Threading a logger, a profiler marker, or a random number source through every constructor in that chain adds noise to code that has nothing to do with those services. A lookup lets the leaf object grab what it needs without making every intermediate object aware of it.

Ambient services. Some things are context, not collaboration. A clock, an input source, a settings object, a frame counter. They are everywhere, they rarely change, and forcing every class to declare them makes signatures heavier without making the code clearer. The line between “ambient context” and “service locator” is thin, and it is mostly a question of discipline.

Engine boundaries. This is the Unity-specific case, and it matters most in practice.

Small games and prototypes. When the whole game is five scenes and three systems, a global registry is fast to build and easy to read. The full dependency-injection apparatus is a tax you do not need to pay yet. The risk is that the small game grows and the registry becomes the default pattern even after it stops being convenient.

The honest position is not “never use it.” It is “know what it costs, and use it where the cost is already being paid for another reason.”

Why Unity leans toward lookup

Unity makes constructor injection awkward in a specific way: the engine constructs your MonoBehaviour components, not your code.

Unity’s own documentation warns against giving MonoBehaviour a constructor, because the engine manages those objects and their lifecycle. That closes off the cleanest injection point. You cannot require an IAudioService in the constructor of a component the engine will create.

That leaves three honest options for Unity components:

1. Constructor injection for plain C# classes. Keep the gameplay logic in ordinary classes that you construct yourself, and inject normally there.
2. Explicit setup methods. A thin MonoBehaviour calls Initialize(IAudioService audio, ISaveService save) from a bootstrapper.
3. Service lookup at the boundary. The component pulls from a registry, accepting the hidden-dependency cost in exchange for not fighting the engine.

The third option is not automatically wrong. It is often the most honest thing to do in a codebase that is mostly Unity components. The trick is to keep the lookup at the boundary and not let it leak into the pure logic.

public sealed class PlayerHud : MonoBehaviour
{
    private IAudioService audio;

    private void Awake()
    {
        // Boundary lookup: the engine made this object, so it pulls its tools.
        audio = Services.Get<IAudioService>();
    }

    public void OnHealthChanged(int current, int max)
    {
        audio.Play(current <= max / 4 ? "low-health" : "health-change");
        healthBar.SetFill((float)current / max);
    }
}

That component is still mostly glue. The real rules live in plain classes that can take a constructor. The lookup is confined to Awake, at the edge, where the engine already forced your hand.

A registry that fails fast

The difference between a tolerable service locator and an awful one is mostly in how it handles the unhappy path.

A locator that returns null for a missing service is the worst version. It pushes the failure into whatever calls the method, usually a null-reference exception deep in a frame, far from the actual mistake.

A locator that throws immediately on a missing registration is far better. It turns the runtime failure into a loud, early one.

public static class Services
{
    private static readonly Dictionary<Type, object> registry = new();

    public static void Register<T>(T service)
    {
        registry[typeof(T)] = service ?? throw new ArgumentNullException(nameof(service));
    }

    public static T Get<T>() =>
        registry.TryGetValue(typeof(T), out var service)
            ? (T)service
            : throw new InvalidOperationException(
                $"No service registered for {typeof(T).Name}.");
}

Three decisions here do most of the heavy lifting:

1. Registration is explicit. Nothing is registered by accident or lazily. A service either exists or it does not.
2. Missing services throw. There is no null to forget to check. The error names the missing type.
3. null is rejected at the door. You cannot register a null service and discover it later.

The remaining rule is ordering: register before you resolve. That means a bootstrap object that runs before gameplay and populates the registry once.

public sealed class GameBootstrap : MonoBehaviour
{
    private void Awake()
    {
        Services.Register<IAudioService>(new UnityAudioService());
        Services.Register<ISaveService>(new JsonSaveService());
        Services.Register<IInputService>(new InputSystemService());
    }
}

If the bootstrap lives in the first loaded scene and every other system is built after it, the ordering is guaranteed by the scene structure rather than by discipline.

Ambient context, the quieter sibling

The term “ambient context” describes a service locator with a narrower job: it exposes a small set of genuinely global values through a static entry point, and nothing else.

The practical difference is scope. A service locator tends to grow into a junk drawer that holds everything. An ambient context holds a handful of things that are legitimately everywhere: time, settings, a small set of core services.

public static class GameContext
{
    private static readonly AmbientServices services = new();

    public static TimeProvider Time => services.Time;
    public static Settings Current => services.Settings;

    public static void Initialize(TimeProvider time, Settings settings)
    {
        services.Time = time;
        services.Current = settings;
    }
}

This is still a locator under the hood. The benefit is restraint: the API surface is deliberately small, and it is obvious at a glance what is ambient and what is not.

The ambient context does not remove the criticisms. It just makes the surface smaller, which makes the hidden coupling easier to audit. That is a real improvement, even if it is a modest one.

Scene scope and teardown

A static registry that lives for the whole process has a second problem beyond hidden dependencies: it leaks services from unloaded scenes.

An audio mixer can live forever. A level-specific enemy spawner should die with the scene that created it. If the player unloads a dungeon and the registry still holds the dungeon’s services, the next scene inherits stale state it never asked for.

The fix is scope, not globalism. Two levels cover most cases:

• Project-wide for services that genuinely last the whole game: audio, settings, input, save.
• Scene-scoped for services that belong to one scene or level, created on load and discarded on unload.

A scene-scoped locator does not have to be a static class. It can be a plain object owned by the scene:

public sealed class SceneServices
{
    private readonly Dictionary<Type, object> registry = new();
    private readonly IServiceProvider project;

    public SceneServices(IServiceProvider project)
    {
        this.project = project;
    }

    public void Register<T>(T service) => registry[typeof(T)] = service!;

    public T Get<T>() =>
        registry.TryGetValue(typeof(T), out var service)
            ? (T)service
            : project.GetService(typeof(T)) is T fallback
                ? fallback
                : throw new InvalidOperationException($"No service for {typeof(T).Name}");
}

The scene locator resolves its own services first and falls back to the project services for the long-lived ones. That gives you the convenience of lookup without the lifetime problem of a single process-wide bag.

This matters more than it sounds, because lifetime bugs in games are the ones that hide until a player does something unexpected: reloads a level, backs out to the menu, reconnects to a match. A registry that never forgets turns those into stale-state bugs that are hard to reproduce and harder to explain.

Where the boundary should sit

The workable rule for a Unity project is a boundary, not a ban.

Use service location:

• inside MonoBehaviour components the engine constructs,
• for ambient services like time, settings, and input,
• in prototypes and small games where a full container is overhead,
• at the edge, to hand off to plain C# systems.

Use dependency injection:

• for plain C# classes that hold the actual logic,
• for stable collaborators like save, audio, and repositories,
• whenever testability of the core logic matters,
• when the object graph is large enough that central wiring earns its keep.

Use neither:

• for local state that one object naturally owns,
• for trivial values that should just be method parameters,
• for a class with no meaningful dependencies at all.

The mistake is not using one or the other. The mistake is using both in the same layer for the same kind of dependency, so nobody can tell which rule applies where.

The real cost, restated

If you take one thing away, take this: the problem was never the global itself.

A global variable is not automatically harmful. What is harmful is a dependency that is invisible, mutable, and order-dependent. A service locator makes dependencies invisible by default. That is the entire criticism, and it is enough.

Constructor injection makes dependencies visible. That is the entire defense, and it is enough too.

So the choice is not between “clean” and “dirty.” It is between two ways of trading visibility for convenience. Service location buys convenience with visibility. That is a fair price in some places and a bad one in others.

The skill is knowing which place you are in.

Common mistakes

Resolving in the middle of gameplay logic. A lookup buried inside a method is the hardest kind to audit. If the component pulls at the boundary in Awake and then treats the reference as a normal field, the damage is contained.

Returning null instead of throwing. A null return spreads the failure to unrelated code. Throw at the Get call and name the missing type.

Registering lazily, on first use. Lazy registration moves the “who sets this up” decision into whatever happens to run first. That turns initialization order into a source of bugs.

Storing request data in the locator. A current enemy position, a damage amount, a selected target: these are not services, they are request data. Putting them in a registry is how a locator becomes a global junk drawer.

Testing against the real registry. Tests that depend on a shared static registry will eventually interfere with each other. If you must test locator-bound code, reset the registry between tests and register fakes explicitly.

Practical takeaway

Treat the service locator as a boundary tool, not a foundation.

Use it where the engine or the environment has already forced a lookup: inside MonoBehaviour components, for ambient services, in prototypes and small games. Make it fail fast, register up front, and keep the lookup out of the core logic.

Use constructor injection for the plain C# classes that do the real work. Keep their dependencies visible, so the code that matters most is also the code that is easiest to read and test.

The pattern is not a sin. It is a trade. The only real mistake is making that trade without knowing you made it.

References

• Robert Nystrom, Service Locator
• Mark Seemann, Service Locator is an Anti-Pattern
• Martin Fowler, Inversion of Control Containers and the Dependency Injection pattern
• Unity Manual, MonoBehaviour
• Coyote Time, Dependency Injection in Unity
• Coyote Time, Build a Simple DI Container in C#

Jev is built for that decision-shaped part of an application. It accepts state and typed questions, then returns answers in a known shape with probabilities. The application still owns the rules, validation, and actions that follow. That split makes Jev worth considering for classification and routing, including a narrow role in GOAP goal selection.

What is Jev?

Jev is a structured decision model from TypeSafe, available through OpenRouter. It belongs to TypeSafe’s System One model family, which is designed for fast decisions inside software. Jev does not write explanations or free-form responses. Instead, the caller supplies a state object and asks one or more typed questions about it.

A state can be a string, an object, or an array of text data. The questions use a small set of primitives: choice, noul, and score. Each primitive declares the kind of answer the caller expects. Jev returns the selected value or probability, rather than asking your program to extract a label from a sentence.

That changes the integration boundary. A chat completion might return “The agent should rest because its fatigue is high,” and code then has to parse “rest” while deciding what to do with the explanation. Jev can instead answer a choice question with a stable value such as FindRest, plus probabilities for the options. The application validates that value and decides whether it is safe to act on.

Jev does not return its reasoning trace. The probabilities help express uncertainty, but they are still model output, not a proof that a decision is correct. If a feature needs a human-readable explanation, store the relevant state and decision data yourself or ask a separate generative model to explain an already validated result.

What is a classifier?

A classifier assigns an input to one or more predefined labels. Given a message, a classifier might choose billing, technical, or sales. Given an agent snapshot, it might choose rest, fulfill-needs, or stay-with-group.

A conventional classifier usually exposes a fixed input/output contract: supply an input, receive a label and often a confidence score. Jev can implement a similar decision, but its questions make the contract explicit in the request. The application says what it is deciding, describes the possible answers, and sends the state those answers should be based on.

That distinction is useful when the labels belong to the application. A Jev choice answer can be a stable ID from a game’s goal registry, an enum-like route key, or a moderation category. The model chooses among the options the caller gives it. The caller still owns the catalogue and what each value means.

Classification can also be single-label or multi-label. If exactly one category should apply, use a choice question. If several independent tags may apply at once, ask a separate yes/no noul question for each tag and apply thresholds in code. Avoid forcing overlapping labels into one choice; Jev must return one of the alternatives, even when more than one label fits.

Calling Jev through OpenRouter

OpenRouter exposes Jev through the Decisions API at https://openrouter.ai/api/alpha/decisions. This is a different request shape from a chat-completions call: send a model, a state, and a questions object. The model ID typesafe/jev-1.13 pins a specific Jev version. OpenRouter also documents a latest-version alias, but a pinned ID is easier to evaluate when the application depends on stable decisions.

The API key belongs on a trusted server. A key embedded in a Unity build can be extracted from the client, so a shipped game should send a compact decision request to its own backend. That backend can authenticate the player, apply rate limits, call OpenRouter, validate the result, and return only the permitted decision to the client. During local experiments, keep the key outside source control and out of player-facing builds.

Here is a small request using the choice primitive:

curl https://openrouter.ai/api/alpha/decisions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": {
      "ticket": "The checkout screen stays blank after I select Pay.",
      "customerTier": "enterprise"
    },
    "questions": {
      "owner": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "Payment processing, invoices, or refunds.",
          "frontend": "Rendering, layout, or browser compatibility.",
          "account": "Login, permissions, or profile settings."
        }
      }
    }
  }'

The response places typed answers under answers. A choice answer includes the selected key and probabilities for the listed options; a confidence value may also be present. The response’s usage reports request cost in usage.cost. Use that value for accounting instead of estimating each call from prompt length.

A .NET backend can send the same body with HttpClient. This client reads the key from the server environment, posts JSON, and returns the parsed response:

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;

public sealed class JevClient
{
    private static readonly HttpClient Http = new HttpClient();

    public async Task<JsonDocument> DecideAsync(
        object state,
        object questions,
        CancellationToken cancellationToken)
    {
        string apiKey = Environment.GetEnvironmentVariable("OPENROUTER_API_KEY");
        if (string.IsNullOrWhiteSpace(apiKey))
            throw new InvalidOperationException("OPENROUTER_API_KEY is not configured.");

        var body = new
        {
            model = "typesafe/jev-1.13",
            state,
            questions
        };

        using var request = new HttpRequestMessage(
            HttpMethod.Post,
            "https://openrouter.ai/api/alpha/decisions");
        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", apiKey);
        request.Content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        using HttpResponseMessage response = await Http.SendAsync(
            request,
            cancellationToken);
        string responseBody = await response.Content.ReadAsStringAsync();
        if (!response.IsSuccessStatusCode)
            throw new HttpRequestException(
                $"OpenRouter returned HTTP {(int)response.StatusCode}.");

        return JsonDocument.Parse(responseBody);
    }
}

Dispose the returned JsonDocument after reading it. In the GOAP example below, the state and questions arguments are the agent snapshot and candidate-goal criteria. Do not send the request to /api/v1/chat/completions and expect Jev’s typed response there; that endpoint is for chat-style models.

Jev answers the questions in one request independently. A second question cannot inspect the first question’s answer. This makes one request useful for several labels about the same state, but it does not turn the questions into a multi-step chain. If the second decision depends on the first, make that dependency explicit in your own code or send a follow-up request with the updated state.

At the time of writing, OpenRouter’s Jev 1.13 page lists a price of $0.042 per million input tokens and no output-token charge. Check the model page before budgeting because rates can change. Jev’s documented context window is 32,000 tokens, but a small state is still preferable: it costs less, reduces irrelevant context, and makes the decision easier to inspect.

Jev’s data types and when to use them

The three primitives describe different decisions. Pick the one that matches the shape of the answer instead of asking the model for a broad judgment and trying to retrofit the result later.

choice: select one option

Use choice when exactly one option should win. The criteria object maps each stable key to a description of when that option applies. Jev returns one key and a probability for each option.

Examples include selecting a support queue, a permitted operation, or one eligible GOAP goal. Add an other or none option when the candidate list may not contain a valid answer. If the application must never accept an unknown value, validate the returned key against its own allowlist anyway.

noul: estimate whether a condition is true

Use noul for a yes/no question. The response contains a probability that the answer is yes. The criteria describe concrete true and false cases, which is more useful than an ambiguous prompt such as “Is this important?”

Examples include asking whether a report describes a defect, whether a message requests a refund, or whether a character’s state suggests an eligible goal. noul questions are independent, so they work for multi-label tagging: ask whether each candidate tag applies, then choose the thresholds that match the product’s tolerance for false positives and false negatives.

score: place something on an ordered scale

Use score when the answer has a real order, such as low, medium, and high urgency. Its criteria are an ordered list from the lowest level to the highest. Jev returns a probability-weighted score and probabilities for the levels; a confidence value may also be present.

A score is not a category with an arbitrary numeric label. The order needs to mean something. “Routine, should be handled today, blocks the simulation” has a progression; “urgent, technical, refund” does not. For a small fixed set of mutually exclusive choices, choice is clearer.

Using Jev to select a GOAP goal

GOAP separates a desired world state from the actions that can make it true. A planner receives a goal and the current world state, then searches the authored action set for a valid plan. Jev can help choose which goal deserves attention when several are eligible. It should not invent actions or replace the planner’s preconditions, effects, and target checks.

A useful boundary looks like this:

A crowd simulation already has structured state that can support this request: agent role, current goal, utility urgency, fulfilled and unfulfilled motivations, relationships, recent events, and the registered goals available to that role. Keep the snapshot compact and send only fields that can change the decision. The goal catalogue should remain authored data with stable wire IDs and descriptions.

For example, a civilian may have high fatigue, an unfulfilled motivation, and a current Idle goal. Local code can first remove goals that are unavailable for that agent role or invalid in the current world. The remaining candidates might be FindRest and FulfillNeeds. A choice request can ask Jev which goal best fits the current snapshot:

{
  "model": "typesafe/jev-1.13",
  "state": {
    "agent": {
      "id": "agent-42",
      "decisionRevision": 18,
      "role": "Civilian",
      "currentGoal": "Idle",
      "fatigueUrgency": "Critical",
      "unfulfilledMotivations": ["Rest", "FindFood"]
    },
    "scenario": {
      "danger": "Low",
      "groupStatus": "Safe"
    },
    "eligibleGoals": ["FindRest", "FulfillNeeds"]
  },
  "questions": {
    "nextGoal": {
      "type": "choice",
      "instructions": "Which eligible goal should this agent pursue next?",
      "criteria": {
        "FindRest": "Reduce critical fatigue by reaching a rest spot.",
        "FulfillNeeds": "Address an unfulfilled motivation when immediate rest is not the stronger need."
      }
    }
  }
}

The descriptions are part of the decision contract. “Find rest” is too vague if the agent needs a particular condition or role. “Reduce critical fatigue by reaching a rest spot” tells Jev what success means without asking it to plan the movement or decide whether a rest spot exists. The code should derive eligibleGoals from the registry and current state, not trust a model to discover which goal classes exist.

The response’s nextGoal.choice can then be mapped through the project’s stable GOAP wire-ID registry. Before requesting a plan, the caller should check all of the following:

• The key parses to a registered goal ID.
• The goal is in the allowlist for this agent and remains eligible.
• The agent and scenario versions still match the snapshot used for the request.
• The answer has enough confidence for the application’s chosen policy.

A small adapter can enforce those checks before handing the goal to the existing GOAP provider. This example fails closed when confidence is missing; its caller can keep the behavior graph’s current decision when it returns false:

using System.Collections.Generic;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

static bool TryApplyChoice(
    string responseJson,
    AgentCortex cortex,
    int requestedDecisionRevision,
    int currentDecisionRevision,
    ISet<GoapGoalId> currentlyEligibleGoals,
    double minimumConfidence)
{
    if (string.IsNullOrWhiteSpace(responseJson) || cortex == null ||
        requestedDecisionRevision != currentDecisionRevision ||
        currentlyEligibleGoals == null)
        return false;

    JObject root;
    try
    {
        root = JObject.Parse(responseJson);
    }
    catch (JsonException)
    {
        return false;
    }

    JToken answer = root["answers"]?["nextGoal"];
    if (answer == null || answer["choice"]?.Type != JTokenType.String)
        return false;

    JToken confidenceToken = answer["confidence"];
    if (confidenceToken == null ||
        (confidenceToken.Type != JTokenType.Float &&
         confidenceToken.Type != JTokenType.Integer))
        return false;

    double confidence = confidenceToken.Value<double>();
    if (confidence < 0 || confidence > 1 || confidence < minimumConfidence)
        return false;

    string wireId = (string)answer["choice"];
    if (!GoapGoalRegistry.TryParseWireId(wireId, out GoapGoalId goalId) ||
        !currentlyEligibleGoals.Contains(goalId))
        return false;

    return cortex.TryExecuteAvailableGoals(new[] { goalId });
}

The example’s currentlyEligibleGoals set should be rebuilt from the current role’s registered goals after deterministic state checks. requestedDecisionRevision must cover every agent and scenario field sent to Jev; increment it whenever any of those inputs changes. The reference snapshot combines AgentContext data with utility urgency and motivations read from other systems, so AgentContext.StateVersion alone may miss a fatigue or motivation change. TryExecuteAvailableGoals adds one final local validation before requesting the goal.

When the response arrives, reject it if the decision revision changed or the selected goal is no longer eligible. If the JSON is malformed or confidence is below the application’s threshold, keep the existing behavior-graph decision or use a deterministic local fallback. Choose that threshold from evaluation data rather than intuition alone.

Once accepted, pass the typed goal to the GOAP provider. The planner still checks its own conditions, sensors, targets, costs, and effects. For FindRest, for example, the goal condition is tied to critical fatigue, and the rest capability has a target sensor for a nearby rest spot. If the sensor finds no usable target or the action becomes invalid, normal GOAP validation and replanning remain responsible for recovery. Jev selected intent; the planner still decides whether the authored plan can run.

The example borrows a useful boundary from a crowd-simulation codebase: build an agent snapshot, limit the candidate list to registered goals, and validate returned IDs and versions. That project’s documentation describes behavior-graph nodes selecting goals in the live runtime, with an LLM interpreting spawn requests. The Jev flow here is a proposed decision provider at the goal-selection boundary, not a claim that Jev already drives that simulation.

Keep the model at the decision boundary

Calling a remote model for every agent on every frame would make latency, cost, and stale responses part of the simulation loop. Schedule decisions when meaningful state changes, batch requests where the API and game design allow it, and keep a deterministic behavior available while a request is in flight. Log the snapshot version, model ID, selected key, probabilities, latency, and usage.cost so the decision can be reviewed later.

Start with one decision boundary and a small candidate set. Log how often Jev’s selection passes validation, how often the local fallback takes over, and whether the chosen goals lead to valid plans. If those measurements do not show a useful change in behavior, keep the existing behavior-graph decision.

References

• Jev on OpenRouter
• OpenRouter Jev tutorial
• Decisions API request reference
• Jev 1.13 model and pricing
• GOAP for Game AI: Let Actions Build the Plan

A validator checks that every status id exists. A balance report totals damage and duration. An editor preview turns the tree into readable text. A build step gathers references so unused assets can be found. Putting all of those jobs on the data nodes couples the model to every tool. Copying a chain of type checks into each tool spreads the same knowledge around.

The Visitor pattern is one way to keep a stable set of node types separate from a growing set of operations. In game code, that can be a useful fit for content validation and editor or build tooling. It is usually a poor fit for every object in a running scene. The choice depends on which side of the model changes more often.

The useful shape of the problem

Visitor works on a known family of element types. Think of a content tree with DamageNode, ApplyStatusNode, and SequenceNode. Those types describe the shape of an ability. They do not decide how the ability is validated, summarized, exported, or previewed.

That separation is useful when the node model is fairly stable but new tools keep appearing. Adding an operation means adding a visitor. The node classes stay focused on representing data and enforcing their own basic invariants. A designer-facing validator can report bad references without giving every node a dependency on the editor. A build report can inspect the same data without adding build-only methods to runtime types.

The trade is deliberate. When a new node type appears, every visitor must decide what that node means. A ConditionalNode added to the tree affects the validator, exporter, balance report, and any other complete visitor. That extra work is a safeguard when skipping the new case would make a report incomplete. It is friction when node types change every week.

Double dispatch, without the fog

C# normally chooses an overloaded method using the argument’s compile-time type. If a method receives an AbilityNode, an overload for DamageNode is not selected merely because the object happens to be a damage node at runtime. Virtual dispatch chooses an implementation based on the runtime type of the receiver; it does not also dispatch on the runtime type of every argument.

Visitor makes two calls. First, the node’s virtual Accept method selects the concrete node implementation. That method then calls the matching overload on the visitor. In a DamageNode.Accept method, this has the compile-time type DamageNode, so C# selects Visit(DamageNode). Those two single-dispatch steps are called double dispatch.

using System;
using System.Collections.Generic;

public interface IAbilityVisitor<TResult>
{
    TResult Visit(DamageNode node);
    TResult Visit(ApplyStatusNode node);
    TResult Visit(SequenceNode node);
}

public abstract class AbilityNode
{
    public abstract TResult Accept<TResult>(IAbilityVisitor<TResult> visitor);
}

public sealed class DamageNode : AbilityNode
{
    public float Amount { get; }

    public DamageNode(float amount) => Amount = amount;

    public override TResult Accept<TResult>(IAbilityVisitor<TResult> visitor)
        => visitor.Visit(this);
}

public sealed class ApplyStatusNode : AbilityNode
{
    public string StatusId { get; }
    public float Duration { get; }

    public ApplyStatusNode(string statusId, float duration)
    {
        StatusId = statusId;
        Duration = duration;
    }

    public override TResult Accept<TResult>(IAbilityVisitor<TResult> visitor)
        => visitor.Visit(this);
}

public sealed class SequenceNode : AbilityNode
{
    public IReadOnlyList<AbilityNode> Children { get; }

    public SequenceNode(IEnumerable<AbilityNode> children)
        => Children = Array.AsReadOnly(new List<AbilityNode>(children).ToArray());

    public override TResult Accept<TResult>(IAbilityVisitor<TResult> visitor)
        => visitor.Visit(this);
}

Each concrete node implements one overload from IAbilityVisitor<TResult>. The visitor’s result type is generic so one operation can return diagnostics, another can return a formatted description, and a third can return a number without stashing results in mutable fields.

For a real content model, the node types also need their data. A status node might expose a status id and duration. A sequence node holds an ordered list of child nodes. The sequence owns that list because ordering is part of the ability’s meaning; visitors choose how to process it. Keeping this model as ordinary C# data also makes it possible to test without loading a scene or constructing MonoBehaviour instances.

A visitor that validates ability content

Validation is a good first operation because its rules are easy to state and its output is useful before a match starts. Damage must be finite and positive. A status needs a non-empty id and a finite, positive duration. A sequence is valid only when its children are valid.

using System;
using System.Collections.Generic;

public sealed class AbilityValidator : IAbilityVisitor<IReadOnlyList<string>>
{
    public IReadOnlyList<string> Visit(DamageNode node)
    {
        if (float.IsNaN(node.Amount) || float.IsInfinity(node.Amount) || node.Amount <= 0f)
            return new[] { "Damage must be finite and greater than zero." };

        return Array.Empty<string>();
    }

    public IReadOnlyList<string> Visit(ApplyStatusNode node)
    {
        var errors = new List<string>();

        if (string.IsNullOrWhiteSpace(node.StatusId))
            errors.Add("Status id is required.");

        if (float.IsNaN(node.Duration) || float.IsInfinity(node.Duration) || node.Duration <= 0f)
            errors.Add("Status duration must be finite and greater than zero.");

        return errors;
    }

    public IReadOnlyList<string> Visit(SequenceNode node)
    {
        var errors = new List<string>();
        foreach (var child in node.Children)
            errors.AddRange(child.Accept(this));
        return errors;
    }
}

The sequence visitor owns the recursive step because it knows that this node contains children. The leaf visitors validate only their own fields. A caller can validate a root with root.Accept(new AbilityValidator()) and show the returned messages in an inspector, content pipeline, or command-line check. A small edit-mode test can protect the traversal contract:

var ability = new SequenceNode(new AbilityNode[]
{
    new DamageNode(12f),
    new ApplyStatusNode("", 3f)
});

var errors = ability.Accept(new AbilityValidator());
if (errors.Count != 1)
    throw new Exception($"Expected one validation error, got {errors.Count}.");

This checks that the sequence visits both children and that invalid status data produces a diagnostic. A larger test suite can assert the exact message and include nested sequences, but this small case catches a missing recursive step.

This example returns errors rather than keeping a list on the visitor instance. That makes each call’s output explicit and avoids stale diagnostics when someone reuses the same visitor for a second asset. For a very large tree, repeated lists and AddRange may allocate more than desired. Measure the editor or build step before changing the API; if it matters, pass a caller-owned result buffer or use a visitor with carefully scoped state.

The model has a cost

The visitor interface lists every concrete element type. That list is the contract for the model. When a new HealNode is introduced, each concrete IAbilityVisitor<TResult> implementation must add Visit(HealNode). The compiler points to implementations that have not been updated.

That pressure is valuable for exhaustive operations. A validator that forgets a new node should not report success by accident. A serializer or balance exporter should make an explicit decision about how healing behaves. If an operation truly does not care about a node, a default visitor can say so, but silent no-op defaults trade away the compiler’s reminder. Use them only for intentionally partial operations, such as a visitor that searches for one optional reference type.

The inverse cost appears when adding operations. A new visitor can be added without changing every node class. This is the pattern’s main benefit. It moves the change cost toward extending operations and away from extending the data hierarchy.

That choice resembles the expression problem: a design cannot make both adding new variants and adding new operations equally cheap. Visitor favors a stable set of variants and many independent operations. If that is not how the game model evolves, the pattern is pushing against the project.

Traversal is a separate decision

Visitor decides which operation handles a node. It does not automatically define how a tree is walked. In the validator above, Visit(SequenceNode) walks the children. A text exporter may walk them in order but add indentation. A dependency collector may need to de-duplicate asset ids. A balance summary may carry totals or context from parent nodes.

Putting traversal in each visitor is simple while the operations genuinely need different traversal rules. It becomes repetitive when several operations must walk exactly the same structure. At that point, consider a small shared walker or a base visitor that traverses children and lets subclasses handle node-specific work. Keep that abstraction narrow. A traversal framework with configurable enter/exit hooks, mutation policies, cancellation, and scheduling is a new subsystem; do not build it for three foreach loops.

A conditional ability node makes the difference concrete. The runtime evaluator follows the branch selected by the current target or game state. A content validator should inspect both branches, including the one that is not active in the editor preview, so a missing status id does not wait until a rare condition occurs. The same node hierarchy can therefore need distinct traversal policies. Sharing dispatch is useful; forcing every operation through one traversal can hide content errors.

Mutation during traversal deserves a clear rule. If a visitor rewrites or removes nodes while iterating the same child collection, ordering and skipped-element behavior become accidental. Prefer visitors that return a replacement tree, or gather edits and apply them after the walk. A reporting visitor should not quietly mutate the data it is reporting on.

A switch can be the better C# answer

A local switch expression often keeps a small external operation shorter than classic Visitor. Keep leaf validation in small helper methods, then make the dispatch explicit:

using System.Collections.Generic;
using System.Linq;

static IReadOnlyList<string> Validate(AbilityNode node) => node switch
{
    DamageNode damage => ValidateDamage(damage),
    ApplyStatusNode status => ValidateStatus(status),
    SequenceNode sequence => sequence.Children
        .SelectMany(Validate)
        .ToArray(),
    _ => throw new NotSupportedException($"Unhandled node type: {node.GetType().Name}")
};

The fallback makes an unknown node fail instead of quietly disappearing. With an open abstract base class, the compiler cannot always prove that the switch covers every subtype. Newer C# versions and analyzers can improve diagnostics for closed type hierarchies, but check the language version and compiler settings actually used by the Unity project. A _ => Array.Empty<string>() fallback is shorter, but it can hide missing behavior.

A switch is often easier to read when there are only one or two operations. It also keeps the data classes unaware of a visitor interface. Classic Visitor becomes more attractive when several operations need their own configuration, result type, lifecycle, or polymorphic selection, or when an existing framework already exposes a visitor API.

Do not create both a visitor interface and a large set of switches for the same hierarchy without a reason. That leaves two dispatch systems to update. Pick the one that matches the model and the language support in the project.

Where it fits in Unity

A Unity project can keep the visited model separate from scene objects. A ScriptableObject may hold authoring data; an import or validation step can convert that data to a plain node graph; visitors can inspect the graph before it produces runtime objects. The exact serialization design is a separate choice. Unity’s serialization support for custom polymorphic data has constraints, so confirm how the project stores the hierarchy rather than assuming that an interface-shaped object graph will serialize automatically.

Unity also provides a Properties API with property bags and property visitors for inspecting .NET objects. That is a better starting point when the job is generic property traversal, such as building inspector-like tooling or walking reflected data. A custom ability visitor is useful when the rules are domain-specific: validate that a status id exists in this game’s catalog, or calculate a balance report using this game’s conventions. Reimplementing generic property walking to handle those rules adds work without adding meaning.

This kind of visitor is most comfortable in editor tooling, content validation, import pipelines, tests, and infrequent debug reports. It can run at runtime too, but a per-frame visitor over thousands of nodes is a design decision worth measuring. Each node visit involves virtual dispatch, and allocating a visitor or result collection on every frame can create avoidable garbage. For frequent gameplay decisions, ordinary methods, data tables, or a purpose-built evaluator may express the behavior with less machinery.

Avoid making GameObject or MonoBehaviour hierarchies accept a new visitor just to calculate ordinary gameplay behavior. Components already expose operations through methods and interfaces. A damage system that needs to apply damage can call an IDamageable contract. Keep the visitor for external passes over a stable structure; use ordinary polymorphic methods for one game object at a time.

Visitor versus Strategy

These two patterns can look similar because both move behavior out of a class. Strategy swaps one algorithm behind a stable interface. A movement controller can choose a ground or flying movement strategy. The context asks one strategy to perform one job.

Visitor applies an operation across several known element types. A balance visitor can visit damage, status, and sequence nodes and compute one report over the complete ability tree. Strategy varies the implementation of one behavior; Visitor varies the operation over a structure. If the code needs one interchangeable behavior at a time, start with Strategy or a normal interface. If it needs many distinct passes over a stable tree, Visitor is worth considering.

A practical decision check

Before adding Accept methods, ask what actually changes in this feature.

• If node types are stable and tooling operations keep growing, Visitor may centralize those operations cleanly.
• If node types change often, prefer methods on the types, a switch with explicit failure, or a model designed for open extension.
• If there is one small operation, write the method or switch first. A visitor interface is unlikely to repay its extra files.
• If the job is generic reflection or property traversal, look for a platform API before writing a custom walker.
• If the work runs in a hot gameplay loop, measure allocations and dispatch cost, then compare the visitor against a direct evaluator.

For a stable ability-data tree, keep validators and reports beside the content pipeline as separate visitors. Keep per-frame combat behavior on gameplay interfaces or a purpose-built evaluator, and add the visitor boundary only when multiple tools are starting to crowd the data model.

References

• Visitor pattern and double dispatch
• Double dispatch explained
• C# pattern matching overview
• Unity Properties and property visitors

The language feature itself is straightforward. A static method whose first parameter is marked with this can be called as though it were an instance member of that parameter’s type. The object is still passed to a static method; C# merely provides more convenient call syntax.

That distinction should guide the design. An extension method does not add state, gain privileged access, or become part of the extended class. It is a small piece of API vocabulary placed near a type. Used carefully, that vocabulary makes gameplay code read in the same order as the operation it describes. Used casually, it creates a second, less visible API for every common Unity type.

The useful question is therefore not “can this be an extension method?” Most static helpers can. The useful question is whether extension syntax makes the call more honest and easier to find without hiding an important dependency or cost.

What the compiler actually does

Consider a compact transform helper:

using UnityEngine;

public static class TransformExtensions
{
    public static void SetX(this Transform transform, float x)
    {
        Vector3 position = transform.position;
        position.x = x;
        transform.position = position;
    }
}

Callers can write this:

playerTransform.SetX(spawnX);

Conceptually, the compiler binds that call to this:

TransformExtensions.SetX(playerTransform, spawnX);

The extension method remains static. It can use only public and otherwise accessible members. It does not modify Transform or participate in its virtual dispatch. The call is resolved at compile time from the receiver’s declared type, the extension methods currently in scope, and the available overloads.

This explains several behaviours that otherwise look surprising.

An actual instance member wins over an extension method with the same applicable signature. If Unity later adds an instance method named SetX, existing source may bind differently after an engine upgrade. An extension declared for a derived type can be selected when the variable is declared as that derived type, but not when the same object is held in a base-typed variable. Adding a using directive can introduce another candidate and turn a previously clear call into an ambiguous one.

Extension methods are compile-time convenience, not runtime decoration. Treating them that way removes much of the mystery.

Use extension syntax when the receiver is the subject

The strongest extension methods describe an operation whose natural subject is the left-hand value. Collection operations are the familiar example: the sequence is filtered, mapped, or searched. Unity code has similar cases.

public static class LayerMaskExtensions
{
    public static bool Contains(this LayerMask mask, int layer)
    {
        return layer >= 0 && layer < 32 && (mask.value & (1 << layer)) != 0;
    }
}

The call reads naturally:

if (damageableLayers.Contains(other.gameObject.layer))
    ApplyDamage(other.gameObject);

The mask is clearly the subject. The helper is deterministic, cheap, and needs no hidden service. Its name describes the result rather than the implementation. Those qualities make extension syntax earn its place.

Compare that with an operation such as this:

public static void SaveToCloud(this PlayerState state)
{
    // Finds authentication, serialization, and network services globally.
}

The sentence is fluent, but the design is not. Saving is not behavior supplied by PlayerState; it requires a destination, credentials, serialization policy, cancellation, retries, and error handling. Hiding those dependencies inside an extension makes the call look local and cheap when it is neither.

Prefer an explicit service:

await cloudSave.SaveAsync(state, cancellationToken);

A useful extension method is usually about the receiver. A suspicious one merely starts from the receiver and then reaches into the rest of the application.

Keep cost visible in the name and shape

A method call does not need to be free, but its cost should be unsurprising. Unity projects are especially sensitive because apparently harmless calls often involve native-engine boundaries, hierarchy walks, physics queries, asset loading, or managed allocations.

This helper is convenient and misleading:

public static T RequireInChildren<T>(this Component component)
    where T : Component
{
    T found = component.GetComponentInChildren<T>(true);
    if (found == null)
        throw new MissingComponentException(typeof(T).Name);

    return found;
}

RequireInChildren at least signals a hierarchy search better than a vague name such as Get. It still should not be called repeatedly from Update. The extension syntax can make the operation feel like direct access to a field on component, even though Unity may inspect a subtree.

A practical rule is to make expensive work visible through verbs and context:

• FindClosestTarget implies a search; ClosestTarget can look like cached data.
• LoadIconAsync exposes both loading and asynchronous completion.
• CopyComponentsTo suggests work proportional to a collection.
• GetOrAddComponent announces that the scene may be mutated.
• ToArray should be assumed to allocate unless documentation proves otherwise.

Do not use an extension method to disguise an operation the caller must budget. If the operation needs caching, batching, cancellation, ownership, or scheduling, a normal object with explicit state is usually a better home.

Do not turn GameObject into a service locator

GameObject, Component, and Transform are tempting receivers because almost every Unity system already has one. That makes them poor places for broad application services.

A helper such as gameObject.PlaySound("hit") might search for an audio manager, load a clip, choose a mixer group, and create a pooled source. Another helper might call transform.ShowDamageNumber(20), then find UI and localization services. Soon every scene object appears able to perform every operation in the game.

This style reduces visible parameters but does not reduce coupling. It moves coupling into static code and global lookup. Tests need more scene setup, execution order matters, and readers cannot tell which systems a method touches from its call site.

Keep engine-type extensions close to engine-type concerns. Converting coordinates, checking a layer mask, iterating direct children, setting one axis, or attempting a well-defined component lookup can fit. Starting quests, saving progress, spawning networked actors, loading addressable content, and submitting telemetry usually do not.

The receiver should carry most of the information needed by the operation. If the method needs three managers and a hidden singleton, extension syntax is polishing the wrong design.

Unity null is not ordinary C# null

An extension method can be invoked with a null receiver because it is a static call underneath. Ordinary instance syntax would throw before entering a method; extension syntax passes null as the first argument.

Transform target = null;
target.SetX(10f); // Enters SetX, then fails when position is accessed.

Unity adds another complication. UnityEngine.Object overloads equality and Boolean conversion so a managed wrapper can behave as null after its native object has been destroyed. Microsoft’s null operators and Unity’s overloaded null semantics are not interchangeable.

That means a generic-looking helper can get the check wrong:

public static bool IsNull<T>(this T value)
{
    return value is null;
}

For a destroyed Unity object, is null checks the managed reference and can report false even though Unity’s overloaded == null reports true. The helper sounds universal while silently choosing one null model.

Do not add IsNull and IsNotNull extensions to a Unity project. They save almost no text and obscure which semantics are required. For Unity objects, use the engine’s intended check directly:

if (target == null)
    return;

For unconstrained managed data where actual reference null is intended, use standard C# null patterns in the local code.

Extensions on UnityEngine.Object should validate the receiver at the boundary when failure would otherwise be cryptic:

public static T RequireComponent<T>(this GameObject gameObject)
    where T : Component
{
    if (gameObject == null)
        throw new System.ArgumentNullException(nameof(gameObject));

    if (gameObject.TryGetComponent(out T component))
        return component;

    throw new MissingComponentException(
        $"{gameObject.name} requires {typeof(T).Name}.");
}

This is suitable for setup and authoring validation, not a per-frame optional query. Throwing is useful when the missing component violates a declared invariant. When absence is expected, Unity’s existing TryGetComponent already expresses the case correctly and needs no wrapper.

Prefer concrete contracts over universal generic helpers

Generic extensions can remove repetition, but broad constraints often produce vague APIs. A method on this T is effectively available everywhere its namespace is imported. The wider the receiver, the more carefully the name must be chosen.

This extension adds little:

public static bool IsOneOf<T>(this T value, params T[] choices)
{
    return choices.Contains(value);
}

It appears on nearly every type, imports LINQ behaviour indirectly, and allocates a params array at typical call sites. In a frame loop, a neat sentence can become recurring garbage. At only two or three choices, direct comparisons are both clearer and cheaper. If the set is reused or large, a cached HashSet<T> expresses the real data structure.

A constrained helper can be more honest:

public static class ComponentExtensions
{
    public static bool TryGetEnabled<T>(this Component owner, out T component)
        where T : Behaviour
    {
        if (owner != null &&
            owner.TryGetComponent(out component) &&
            component.enabled)
        {
            return true;
        }

        component = null;
        return false;
    }
}

Even here, the narrower promise matters: this operation applies only to Behaviour components and succeeds only when the sibling component is enabled. Inspect the intended Unity version and component-query behaviour before standardizing any lookup helper. A project-local helper should match the engine version the project actually ships, not a remembered limitation from an older release.

The general lesson is to constrain both the type and the promise. LayerMask.Contains(int) says more than Object.Matches<T>(). A narrow extension is easier to discover, harder to misuse, and less likely to collide with another package.

Avoid hidden allocations in fluent chains

Fluent syntax encourages chaining, and chaining can conceal intermediate work. LINQ is valuable in editor tooling, setup code, and many low-frequency systems. It can also allocate enumerators, iterators, closures, and result collections depending on the operators, source type, runtime, and materialization step.

An extension does not need LINQ to allocate. Common traps include:

• params arrays created at each call site
• capturing lambdas that create closures
• iterator methods using yield return
• string interpolation used only for disabled logging
• returning a new list or array for every query
• boxing a struct through an interface
• repeated component or hierarchy searches presented as accessors

Suppose a targeting helper returns a fresh list:

public static List<Enemy> InRange(
    this IReadOnlyList<Enemy> enemies,
    Vector3 origin,
    float radius)
{
    var result = new List<Enemy>();
    float radiusSquared = radius * radius;

    for (int i = 0; i < enemies.Count; i++)
    {
        Enemy enemy = enemies[i];
        if (enemy != null &&
            (enemy.transform.position - origin).sqrMagnitude <= radiusSquared)
        {
            result.Add(enemy);
        }
    }

    return result;
}

The implementation avoids a square root but still allocates a list on every call. A reusable output buffer makes ownership and lifetime explicit:

public static void CollectInRange(
    this IReadOnlyList<Enemy> enemies,
    Vector3 origin,
    float radius,
    List<Enemy> results)
{
    results.Clear();
    float radiusSquared = radius * radius;

    for (int i = 0; i < enemies.Count; i++)
    {
        Enemy enemy = enemies[i];
        if (enemy != null &&
            (enemy.transform.position - origin).sqrMagnitude <= radiusSquared)
        {
            results.Add(enemy);
        }
    }
}

This version is less mathematically fluent, but game-loop ownership is clearer: the caller supplies storage and knows that the method clears it. Document that mutation because it is part of the contract.

Do not rewrite every query into a buffer API pre-emptively. Profile the player build and optimize code that runs often enough to matter. The corrective point is narrower: extension syntax does not make allocations disappear, so inspect the implementation before putting a pleasant chain in a hot path.

Choose namespaces as part of the API

Extension methods become candidates through namespace imports. Namespace design therefore controls discoverability and collision risk.

Putting every helper in a root namespace such as Game makes all extensions appear almost everywhere. That feels convenient until unrelated methods crowd autocomplete or two packages define the same name for the same receiver.

Group extensions by stable technical concern:

Game.Foundation.Collections
Game.Foundation.Unity
Game.Editor.AssetPipeline
Game.Combat.Targeting

Keep editor-only extensions in an editor assembly, not merely behind scattered compiler directives. Runtime code should not see helpers that depend on UnityEditor. Assembly definition files provide a stronger boundary than naming alone and prevent accidental player-build references.

Avoid generic class names such as Extensions repeated across many files. The containing class is rarely visible at the call site, but it matters in stack traces, static-call syntax, code search, and conflict diagnosis. TransformExtensions, LayerMaskExtensions, and SerializedPropertyExtensions state their scope plainly.

Public packages need even more restraint. An extension imported by a package consumer can conflict with that consumer’s own vocabulary. Keep package extensions in a package-specific namespace and expose only the ones that carry real semantic value. internal is a good default for helpers that exist solely to tidy one assembly.

Name methods for outcomes, not tricks

Good extension names survive after the implementation is forgotten. They describe a result, a mutation, or a query with normal C# conventions.

A few distinctions matter:

• Use Try... when failure is expected and returned as a Boolean.
• Use Get... for retrieval, not creation or global search unless the rest of the API already establishes that convention.
• Use GetOrAdd... when the operation may mutate the receiver.
• Use Collect... or Copy...To when caller-owned output is filled.
• Use To... when a conversion commonly creates a new value.
• Add Async when the method returns asynchronous work.
• Reserve Require... for invariant checks that fail loudly.

Avoid names such as Safe, Smart, Fast, and Better. They do not define behaviour. SafeDestroy is especially unhelpful: safe with respect to Edit mode, delayed destruction, null inputs, undo support, or asset objects? A method that has different runtime and editor behaviour should state the actual policy and live in the appropriate assembly.

Boolean helpers should read as predicates. mask.Contains(layer) is clear. layer.IsIn(mask) can also work, but it makes an integer the subject and spreads game-specific vocabulary across a primitive type. Prefer the receiver that owns the concept.

Ref extensions and mutation need extra care

C# permits extension methods that receive some value types by reference. They can mutate the caller’s variable rather than a copy. This is useful in narrow data-oriented code, but surprising mutation is worse than a few extra characters.

For ordinary Unity vectors, returning a changed copy is usually clear:

public static Vector3 WithY(this Vector3 value, float y)
{
    value.y = y;
    return value;
}

Usage makes assignment visible:

velocity = velocity.WithY(jumpSpeed);

A ref this Vector3 extension could mutate velocity in place, but that syntax is easy to mistake for normal instance behaviour and does not work on every temporary or property value. The returned-copy form follows Unity’s existing value-type style and composes without hidden mutation.

For a project-owned performance-critical struct, a ref extension may be justified after measurement. Put it in a narrow namespace, use a mutation verb, and test it. Do not create a general ref-based vocabulary for Unity structs merely because the language allows it.

Test extension methods as ordinary static functions

Small, deterministic extensions should have small, deterministic tests. They do not need a scene when the contract is pure.

using NUnit.Framework;
using UnityEngine;

public sealed class LayerMaskExtensionsTests
{
    [Test]
    public void Contains_ReturnsTrueOnlyForIncludedLayer()
    {
        LayerMask mask = (1 << 3) | (1 << 7);

        Assert.That(mask.Contains(3), Is.True);
        Assert.That(mask.Contains(7), Is.True);
        Assert.That(mask.Contains(2), Is.False);
        Assert.That(mask.Contains(-1), Is.False);
        Assert.That(mask.Contains(32), Is.False);
    }
}

Call pure methods with static syntax in tests when that makes the mechanism clearer:

Assert.That(LayerMaskExtensions.Contains(mask, 3), Is.True);

For helpers around GameObject, component lookup, or destroyed-object semantics, use an Edit Mode test that creates and destroys the minimum object graph. Check both ordinary null and a destroyed Unity object when the method claims to handle Unity objects.

Performance-sensitive extensions need a different check. Profile representative calls in a player build, inspect managed allocations, and compare the extension with the direct operation it replaces. Microbenchmarks can isolate a helper, but frame impact still depends on call frequency and surrounding engine work.

The method’s small size is not a reason to skip verification. Small helpers spread widely, so a mistaken edge case gets multiplied across the codebase.

Review the call site, then review the hidden static call

Extension syntax is successful when both views look reasonable.

First, read the fluent call:

if (damageableLayers.Contains(other.gameObject.layer))
    damageQueue.Add(hit);

It should read naturally and put the operation’s real subject on the left.

Then mentally expand it:

if (LayerMaskExtensions.Contains(
        damageableLayers,
        other.gameObject.layer))
{
    damageQueue.Add(hit);
}

That form should still have an honest parameter list. If the static version reveals that the method actually needs global services, mutates distant state, allocates multiple collections, or performs a large search, the fluent version is hiding too much.

A useful code-review checklist is short:

1. Does the receiver own the concept?
2. Is the cost unsurprising from the name?
3. Are dependencies passed explicitly?
4. Are Unity null semantics handled intentionally?
5. Is mutation visible?
6. Is the namespace narrow enough?
7. Does an existing .NET or Unity API already say this clearly?
8. Would a normal service, component, or plain static method be more honest?

The seventh question deletes a surprising number of helpers. Unity already provides TryGetComponent; C# already provides collection and null operations; project code does not need aliases for every API whose name is a few characters longer than preferred.

Practical takeaway

Extension methods are best used as a thin layer of vocabulary, not a hidden architecture.

Choose a receiver that is genuinely the subject of the operation. Keep the method narrow, deterministic where possible, and explicit about searches, allocations, mutation, asynchronous work, and failure. Respect Unity’s special object lifetime and null behaviour. Use constrained types and focused namespaces instead of making universal helpers appear on every object. Keep editor helpers in editor assemblies and package helpers in package-specific namespaces.

Most importantly, expand the call in your head. If the static version would look dishonest because it hides services or substantial work, extension syntax does not improve it. If the static version is a small operation whose first argument clearly owns the concept, the extension can make gameplay code easier to read without making it harder to reason about.

That is the standard worth keeping: clearer at the call site, equally clear underneath.

References

• Microsoft Learn: Extension members
• Microsoft Learn: Extension member design guidelines
• Unity Scripting API: Object
• Unity Scripting API: Component.TryGetComponent
• Unity Manual: Garbage collection best practices

The difficult bugs arrive later. A Boolean occupies a different number of bytes than expected. A struct gains a field and its alignment changes. A native library keeps a callback after the managed delegate has been collected. An error message points to memory that was already released. Everything behaves in the Editor, then an IL2CPP build fails because ahead-of-time compilation has different constraints.

Those failures all point to a broken contract at the language boundary.

Marshalling is the work required to move values between managed C# and unmanaged native code. Some values can cross unchanged. Others need conversion, copying, pinning, allocation, or an explicit lifetime rule. A reliable Unity plug-in keeps that contract narrow enough to inspect and predictable enough to test.

Unity gameplay code
        |
        v
managed wrapper  -- validation, ownership, Unity-friendly types
        |
        v
C ABI            -- fixed widths, explicit buffers, error codes
        |
        v
C++ implementation -- classes, templates, threads, native libraries

Most of the integration work belongs in the managed wrapper and C ABI. The DllImport declaration only describes the call.

Export C, implement C++

C++ is a poor binary interface between independently built modules. Function names can be mangled, exceptions depend on compatible runtimes, class layouts are compiler-sensitive, and standard-library types such as std::string or std::vector are implementation details rather than portable wire formats. A small C-compatible API keeps those compiler-specific details inside the plug-in.

// game_native.h
#pragma once
#include <stdint.h>

#if defined(_WIN32)
    #define GAME_API extern "C" __declspec(dllexport)
#else
    #define GAME_API extern "C" __attribute__((visibility("default")))
#endif

struct NativePoint
{
    float x;
    float y;
    float z;
};

// Returns the number of output points, or a negative error code.
GAME_API int32_t path_smooth(
    const NativePoint* input,
    int32_t input_count,
    NativePoint* output,
    int32_t output_capacity);

The implementation behind path_smooth can use classes, templates, SIMD code, or a third-party navigation library. None of those choices leak into C#. The exported surface uses fixed-width integers, pointers, a plain struct, and a documented return convention.

extern "C" prevents C++ name mangling. The export macro makes the symbol visible from the dynamic library. The fixed-width int32_t avoids the platform-dependent meaning of types such as long, and the caller-owned buffers keep memory ownership explicit.

Treat the exported header as a protocol definition. Once builds ship against it, changing field order or parameter meaning is an ABI change even if the C++ compiler accepts the edit.

Match the signature exactly

The corresponding Unity declaration can stay small:

using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
internal struct NativePoint
{
    public float X;
    public float Y;
    public float Z;
}

internal static class GameNative
{
    private const string Library = "game_native";

    [DllImport(Library,
        EntryPoint = "path_smooth",
        CallingConvention = CallingConvention.Cdecl,
        ExactSpelling = true)]
    internal static extern int PathSmooth(
        [In] NativePoint[] input,
        int inputCount,
        [Out] NativePoint[] output,
        int outputCapacity);
}

The declaration must describe the C function exactly: parameter order, widths, signedness, calling convention, layout, and direction.

Microsoft recommends LibraryImport for modern .NET 7-or-newer applications when source-generated interop is available. Unity projects still need to account for the scripting runtime, Unity version, selected backend, and target platforms they actually ship. DllImport remains the conservative choice across many Unity configurations because the engine’s supported toolchain matters more than general .NET fashion.

Keep all imports in one internal class. Gameplay code should call a managed wrapper, not scatter P/Invoke declarations through MonoBehaviours. That wrapper can validate lengths, reuse buffers, turn error codes into useful exceptions, and convert between Vector3 and the boundary type.

Prefer data that is already the right shape

A blittable type has the same bit-level representation on both sides of the boundary. Values such as byte, int, uint, long, float, double, pointers, and fixed-layout structs made only from blittable fields are the easiest values to pass. The runtime does not need to translate each field into another representation.

That is why NativePoint contains three float fields rather than a managed object reference. Sequential layout makes the field order explicit. The native and managed definitions still need an agreement about packing and alignment, but this shape is straightforward on the usual Unity targets.

A few innocent-looking types deserve suspicion:

• C# bool does not have one universal native representation. A C++ bool is commonly one byte, while default P/Invoke rules can map a managed Boolean to a four-byte Windows BOOL.
• C and C++ long change width across common platforms. C# long is always 64 bits.
• char and wchar_t do not provide one portable text encoding across Windows, Linux, and macOS.
• Enums need an explicitly agreed underlying integer type.
• References, strings, arrays, and nested managed objects are not plain bytes with self-evident ownership.

A stable plug-in interface can avoid most custom attributes by using int32_t status values, uint8_t flags, fixed-width enum storage, and UTF-8 byte sequences. Explicit types remove entire categories of platform bugs.

If the native API cannot be changed and truly exposes a one-byte Boolean, say so in C#:

[return: MarshalAs(UnmanagedType.U1)]
internal static extern bool IsReady();

For a new API, returning int32_t and interpreting zero or nonzero in the managed wrapper is often even clearer.

Arrays need a length and a direction

A pointer does not carry its element count. Every array crossing a C boundary therefore needs a length, and every output buffer needs a capacity.

The path_smooth contract follows a useful pattern:

1. C# allocates or rents the output array.
2. C# passes the input length and output capacity.
3. C++ never writes beyond that capacity.
4. C++ returns the number of elements written or a negative error code.

That pattern avoids returning a native allocation whose owner is unclear. It also lets the managed side reuse arrays across frames instead of creating garbage for every call.

The convenient [In] and [Out] array signature is a good starting point for occasional or coarse-grained work. A high-frequency call may need unsafe code with pinned spans or direct pointers to remove marshaller decisions and intermediate copies. Do not start there without a measurement. A single native call processing 2,000 points is usually a better boundary than 2,000 calls processing one point each.

Crossing the boundary has fixed overhead. More importantly, conversion and copying can dominate tiny native operations. Batch work so native code does enough useful computation to justify the trip.

Strings are bytes plus an encoding contract

char* does not mean “string” with enough precision for an ABI. It means a pointer to character-sized storage. The contract must also define:

• the encoding
• whether the data is null-terminated or length-delimited
• whether null is allowed
• who allocated the memory
• how long the pointer remains valid
• who releases it

UTF-8 is the practical cross-platform default for a new Unity plug-in. It avoids the platform differences around wchar_t and matches Unity’s guidance for string values returned by native methods on iOS.

Input strings that native code only reads during the call can be declared with explicit UTF-8 marshalling:

[DllImport(Library, CallingConvention = CallingConvention.Cdecl)]
internal static extern int LoadRegion(
    [MarshalAs(UnmanagedType.LPUTF8Str)] string path);

Output strings deserve a stricter design. Returning const char* is safe only if the lifetime is documented and the managed side copies it before the pointer becomes invalid. Returning an allocated char* requires a matching native free function, and that free function must use the same allocator that created the memory.

A caller-owned buffer is often easier to reason about:

// Returns required bytes including the null terminator.
// Writes only when output_capacity is large enough.
GAME_API int32_t get_last_error(char* output, int32_t output_capacity);

C# can ask for the required size, rent a byte[], call again, and decode the bytes as UTF-8. There is more ceremony, but ownership is unambiguous. It also avoids relying on StringBuilder, whose marshalling can create multiple buffers and copies.

Never release native memory with Marshal.FreeHGlobal unless the native API explicitly allocated it using the matching mechanism. “Both are unmanaged memory” is not an ownership contract.

Opaque handles keep C++ objects private

Sometimes the plug-in needs long-lived native state: a pathfinding world, audio processor, compression context, or hardware connection. Passing a C++ class pointer directly and pretending C# understands the object is the wrong abstraction.

Expose an opaque handle instead:

struct NavWorld;

GAME_API NavWorld* nav_world_create(const NativePoint* vertices, int32_t count);
GAME_API int32_t nav_world_query(NavWorld* world, NativePoint from, NativePoint to);
GAME_API void nav_world_destroy(NavWorld* world);

C# sees the pointer as an IntPtr or, preferably, a SafeHandle wrapper. It cannot inspect the C++ object, and it should not try. Its responsibilities are to reject a null result, keep the handle alive during calls, and release it exactly once through nav_world_destroy.

SafeHandle is preferable to hand-written finalization because it exists specifically to model native resource ownership. An IDisposable managed façade can own the safe handle and provide Unity-friendly methods. The rest of the project never needs to see IntPtr.

The destroy function is part of the ABI, not optional cleanup. Native leaks are especially painful in the Editor because disabled domain reload settings and repeated play sessions can make lifetime mistakes appear inconsistent.

Callbacks reverse every lifetime assumption

A callback lets native code call a managed function pointer. It is useful for progress reports, log messages, asynchronous completion, and events from native middleware. It also introduces three separate constraints: signature, delegate lifetime, and thread affinity.

A Unity-compatible callback shape commonly looks like this:

using AOT;
using System;
using System.Runtime.InteropServices;

internal static class NativeCallbacks
{
    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    internal delegate void LogCallback(int level, IntPtr utf8Message);

    // Root the delegate for as long as native code may call it.
    private static readonly LogCallback Log = OnNativeLog;

    [DllImport("game_native", CallingConvention = CallingConvention.Cdecl)]
    private static extern void RegisterLogCallback(LogCallback callback);

    internal static void Register() => RegisterLogCallback(Log);

    [MonoPInvokeCallback(typeof(LogCallback))]
    private static void OnNativeLog(int level, IntPtr utf8Message)
    {
        // Copy the message, then enqueue it for the Unity main thread.
        // Do not call UnityEngine APIs if the native caller may be a worker thread.
    }
}

For AOT builds, Unity documents static callback methods marked with MonoPInvokeCallback. The exact delegate signature and calling convention still have to match the native function pointer.

The static field keeps the delegate alive after the registration call returns. Native code may store that function pointer and invoke it much later. If managed code drops its last delegate reference, the native library can call into collected state. Keep the delegate rooted until native code unregisters it and can no longer issue callbacks.

A callback also runs on whichever thread invoked it. If a native worker thread reports completion, the callback is on that worker thread. Most Unity APIs belong on the main thread, so the callback should copy the payload into managed-owned data and enqueue it. Update or another main-thread pump can consume the queue.

Do not let exceptions escape a reverse P/Invoke callback. Catch them at the managed boundary, record the failure, and return a defined status if the callback signature permits one.

Errors must cross as data, not exceptions

C++ exceptions should stop before the exported C function returns. Allowing one to unwind through managed frames is undefined territory and can terminate the process.

Catch exceptions inside the native wrapper and convert them into a stable error code:

GAME_API int32_t path_smooth(/* arguments */)
{
    try
    {
        // Validate pointers and capacities, then call the C++ implementation.
        return perform_path_smoothing(/* arguments */);
    }
    catch (const std::bad_alloc&)
    {
        return -2;
    }
    catch (...)
    {
        return -1;
    }
}

The managed façade can translate -1 into a NativePluginException, preserve -2 as an out-of-memory failure, or return a normal result object. Both sides still need to agree on what each value means.

Validation belongs on both sides. C# should reject mismatched counts before paying for a native call. C++ should still reject null pointers, negative lengths, and impossible capacities because the native boundary is a trust boundary. A bad pointer does not produce a friendly Unity exception; it can take down the player.

Editor success does not prove player success

Unity native plug-ins vary by platform. Windows loads a DLL, macOS typically uses a bundle or dynamic library, Linux uses a shared object, and iOS commonly links native source or a static library into the player. On statically linked Apple targets, the import name is commonly "__Internal" rather than a file name.

The Unity Inspector also controls which platforms and CPU architectures import a plug-in. A correct C# declaration cannot load an x86-64 library into an ARM64 player. File placement, import settings, exported symbol visibility, architecture, and dependent native libraries all belong to the deployment contract.

IL2CPP adds an AOT step, so test the actual backend early. Callback preservation, unsupported generic paths, and platform linker behavior are not exercised by an Editor session running Mono. A minimal development player that loads the plug-in and performs one call catches more useful failures than another hour staring at attributes.

Keep platform selection close to the interop class:

#if UNITY_IOS && !UNITY_EDITOR
private const string Library = "__Internal";
#else
private const string Library = "game_native";
#endif

Conditional compilation should choose the library location, not hide incompatible ABI designs. The exported function and data contract should remain the same wherever possible.

Put version and size checks in the API

Interop failures are often silent layout disagreements. Add cheap probes that make those disagreements loud:

GAME_API uint32_t interop_abi_version();
GAME_API int32_t interop_sizeof_native_point();

In a development build, the managed wrapper can compare the returned ABI version with its expected constant and compare native sizeof(NativePoint) with Marshal.SizeOf<NativePoint>(). Fail at startup with a useful message rather than corrupting a buffer during a match.

A small boundary test should cover:

• minimum and maximum integer values used by the API
• a struct round trip with distinctive field values
• empty, one-element, and full-capacity arrays
• non-ASCII UTF-8 text
• a deliberately undersized output buffer
• every documented error code
• callback registration, invocation, and unregistration
• repeated create/destroy cycles for opaque handles
• the Editor and at least one IL2CPP development player

The test does not need a framework. A tiny scene or command-line test program that asserts these cases is enough. Boundary tests are valuable because they fail near the mismatch instead of several systems later.

Keep the boundary coarse and dull

A native plug-in earns its maintenance cost when it provides something C# cannot reasonably provide: existing middleware, platform APIs, specialized codecs, hardware integration, or measured performance in a substantial computation. Choosing C++ only because it sounds faster is weak justification. Per-object native calls from Update, marshalled strings in a hot loop, and tiny functions that bounce across the ABI can erase the expected gain. Native code also adds builds, symbols, deployment rules, crash debugging, and architecture-specific artifacts.

Start with one managed façade per native subsystem. Batch inputs. Reuse buffers. Keep exported functions few. Keep C++ objects behind handles. Make ownership visible in function names and documentation. Measure the whole call path in a player build, including conversion and copying, rather than timing only the inner native algorithm.

A good boundary is deliberately less expressive than either language. It uses plain data because plain data survives compiler changes, backend changes, and platform changes.

Check the contract before adding another export

Before adding the next native function, write its contract beside the declaration: exact widths and layout, buffer bounds, string encoding, memory ownership, error behavior, and callback lifetime or thread rules. Add one boundary test that calls it from an IL2CPP development player. If any of those rules remain unclear, the function is not ready to ship.

References

• Unity Manual: Native plug-ins
• Unity Manual: Create callbacks from native code
• Microsoft Learn: Native interoperability best practices
• Microsoft Learn: Type marshalling
• Microsoft Learn: Marshalling a delegate as a callback method

Inheritance handles one fixed variation reasonably well. It handles combinations badly. FireSword, CriticalFireSword, and LifeStealCriticalFireSword are not a healthy class hierarchy; they are a list of feature permutations disguised as types. A boolean-heavy base class is not much better. It moves the combinations into branches and leaves one object responsible for every possible rule.

The decorator pattern offers another shape. A decorator implements the same interface as the object it wraps. It forwards the operation to that wrapped object while adding work before or after the call. Because a decorator can wrap another decorator, small behaviors can be assembled into a stack.

That is the attractive part. The corrective part is that decorators are not a universal status-effect system. Wrapper order matters, runtime inspection can be awkward, and careless assembly can allocate far too often. The pattern works best when the operation has a stable interface and the optional layers have clear ownership.

The useful definition

A decorator has three defining properties:

1. It implements the same contract as the wrapped component.
2. It stores another implementation of that contract.
3. It delegates to the wrapped implementation while adding behavior.

The shared contract is what makes recursive composition possible. Code expecting an IAttack can receive a plain attack, one wrapped in a critical-hit rule, or a stack containing critical damage, fire damage, and life steal. The caller still invokes one method.

caller
  -> life steal
      -> critical hit
          -> basic weapon attack
      <- damage result
  <- heal from actual damage dealt

Work can happen while the request travels inward, while the result travels outward, or both. A critical decorator may modify the attack request before forwarding it. A life-steal decorator may wait for the inner attack to finish, then heal from the damage actually dealt.

That two-way flow is more important than the usual “wrapper” metaphor. It lets a layer transform input, observe output, enforce a condition, or add a side effect without changing the caller or the base operation.

Start with one narrow gameplay operation

A decorator interface should describe one cohesive operation. Avoid starting with a broad IGameObject interface containing movement, rendering, damage, saving, audio, and interaction. Any wrapper implementing that contract would either forward dozens of unrelated members or quietly become another god object.

An attack-resolution seam is narrow enough for a useful example:

public interface IAttack
{
    DamageResult Execute(AttackContext context);
}

public readonly struct AttackContext
{
    public AttackContext(Actor source, Actor target)
    {
        Source = source;
        Target = target;
    }

    public Actor Source { get; }
    public Actor Target { get; }
}

public readonly struct DamageResult
{
    public DamageResult(int attempted, int dealt)
    {
        Attempted = attempted;
        Dealt = dealt;
    }

    public int Attempted { get; }
    public int Dealt { get; }
}

DamageResult deserves to exist even in a small example. Downstream behavior usually needs the result of resolution, not merely the requested amount. Armor, immunity, shields, and clamping can all make actual damage lower than attempted damage. Life steal based on the original number is a common bug.

The concrete component performs the ordinary operation:

public sealed class WeaponAttack : IAttack
{
    private readonly int damage;

    public WeaponAttack(int damage)
    {
        if (damage < 0)
            throw new ArgumentOutOfRangeException(nameof(damage));

        this.damage = damage;
    }

    public DamageResult Execute(AttackContext context)
    {
        int dealt = context.Target.TakeDamage(damage);
        return new DamageResult(damage, dealt);
    }
}

This class should remain boring. It is the center of the composition, not a registry of every optional rule the game may add later.

A base decorator should only remove repetition

The formal version of the pattern often includes an abstract base decorator. In C#, that class is useful when it removes forwarding boilerplate. It should not become a second inheritance framework.

public abstract class AttackDecorator : IAttack
{
    protected AttackDecorator(IAttack inner)
    {
        Inner = inner ?? throw new ArgumentNullException(nameof(inner));
    }

    protected IAttack Inner { get; }

    public abstract DamageResult Execute(AttackContext context);
}

A critical-hit layer can now make a decision and adjust the result. For clarity, this example receives randomness through an interface rather than calling a global random generator. That makes the rule deterministic in tests and lets a server-authoritative simulation provide its own random stream.

public interface IRandomSource
{
    float Next01();
}

public sealed class CriticalAttack : AttackDecorator
{
    private readonly IRandomSource random;
    private readonly float chance;
    private readonly int multiplier;

    public CriticalAttack(
        IAttack inner,
        IRandomSource random,
        float chance,
        int multiplier) : base(inner)
    {
        if (chance < 0f || chance > 1f)
            throw new ArgumentOutOfRangeException(nameof(chance));
        if (multiplier < 1)
            throw new ArgumentOutOfRangeException(nameof(multiplier));

        this.random = random ?? throw new ArgumentNullException(nameof(random));
        this.chance = chance;
        this.multiplier = multiplier;
    }

    public override DamageResult Execute(AttackContext context)
    {
        DamageResult result = Inner.Execute(context);
        if (random.Next01() >= chance)
            return result;

        int bonusRequested = result.Attempted * (multiplier - 1);
        int bonusDealt = context.Target.TakeDamage(bonusRequested);

        return new DamageResult(
            result.Attempted + bonusRequested,
            result.Dealt + bonusDealt);
    }
}

There are several valid ways to model a critical hit. It could multiply a damage request before mitigation instead of issuing bonus damage afterward. It could affect only physical damage, or it could duplicate all child effects. Those choices are game rules, not pattern details.

The example deliberately makes the choice visible. The decorator does not make combat semantics correct by itself. It only gives the rule a composable home.

Result-side behavior is where wrapping becomes valuable

Life steal demonstrates why a returned result is useful:

public sealed class LifeStealAttack : AttackDecorator
{
    private readonly float fraction;

    public LifeStealAttack(IAttack inner, float fraction) : base(inner)
    {
        if (fraction < 0f || fraction > 1f)
            throw new ArgumentOutOfRangeException(nameof(fraction));

        this.fraction = fraction;
    }

    public override DamageResult Execute(AttackContext context)
    {
        DamageResult result = Inner.Execute(context);
        int healing = (int)MathF.Floor(result.Dealt * fraction);
        context.Source.Heal(healing);
        return result;
    }
}

The layer does not need to understand armor, shields, or how the attack produced damage. It depends on one explicit fact: the amount actually dealt. This is a good decorator boundary because the added behavior is local and the inner implementation remains interchangeable.

Assembly happens at a composition root such as an equipment factory, character loadout builder, or match setup system:

IAttack attack = new WeaponAttack(damage: 20);
attack = new CriticalAttack(attack, combatRandom, chance: 0.25f, multiplier: 2);
attack = new LifeStealAttack(attack, fraction: 0.20f);

DamageResult result = attack.Execute(new AttackContext(player, enemy));

The calling code sees one IAttack. The stack can be configured once when equipment changes rather than reconstructed for every swing.

That last point matters in a game loop. The pattern creates object graphs. If code builds a fresh chain on every shot, every AI tick, or every card preview, the architectural neatness may arrive with avoidable garbage collection. Compose on loadout changes, pool where measured, or use value-oriented pipelines for truly hot paths.

Order is part of the design

Decorators look modular, but they are not automatically independent. The order of wrappers can change the result.

Consider these two stacks:

LifeSteal(Critical(BaseAttack))
Critical(LifeSteal(BaseAttack))

In the first stack, life steal sees the combined result returned by the critical layer. In the second, life steal completes before the outer critical layer applies its bonus. The player heals for different amounts.

The same issue appears with elemental conversion, clamping, shields, logging, cooldown gates, and analytics. A logger outside the stack observes the final result. A logger inside observes only what happened beneath it. A clamp before a multiplier differs from a clamp after it.

Treat ordering as a game rule rather than an incidental constructor detail. A practical project can define a small number of phases:

• validation and permission checks
• input conversion
• base operation
• result modifiers
• side effects
• observation and reporting

Not every game needs a general pipeline framework. Often one clearly named factory method and a test for the expected order are enough:

public static IAttack BuildVampireBlade(
    int damage,
    IRandomSource random)
{
    IAttack attack = new WeaponAttack(damage);
    attack = new CriticalAttack(attack, random, 0.25f, 2);
    return new LifeStealAttack(attack, 0.20f);
}

If designers must reorder dozens of effects at runtime, a list of explicit modifiers with phases and priorities may be more transparent than nested wrappers. Decorator is a composition technique, not an excuse to hide ordering policy.

Do not confuse decorators with stat modifiers

A stat system often needs to answer questions that a wrapper chain answers poorly:

• Which effects currently contribute to this value?
• Remove the modifier from item instance 417.
• Stack poison up to five times, then refresh its duration.
• Serialize all active effects.
• Show each contribution in a tooltip.
• Recalculate only when a dependency changes.

Those requirements point toward data records in a collection, not anonymous layers in a recursive object graph. A list of modifiers can be filtered, sorted, grouped, saved, and displayed directly.

Decorators are a better fit when behavior must surround an operation. Examples include retrying a request, measuring an operation, gating an ability, adding a post-hit effect, caching a query, or translating the input and output of a service.

The distinction is not “numbers versus behavior.” It is about the operations the rest of the game needs. If removal by identity, UI explanation, duration, and persistence are central, model those concepts explicitly. Do not force them through wrappers because the initial class diagram looks tidy.

A hybrid is common. ScriptableObject assets or plain data records describe effects. A factory reads those definitions and creates a runtime attack stack for a loadout. The persistent model remains inspectable, while the runtime operation remains small.

Decorator, strategy, command, and chain are not synonyms

Several patterns use composition and can look similar in C#.

Strategy swaps the implementation of an operation. A flying movement strategy replaces a walking movement strategy. Decorator keeps an implementation and surrounds it with additional behavior. Strategy changes the core choice; decorator layers optional responsibilities around a compatible core.

Command represents a request as data or an object that can be queued, recorded, or undone. A command may call a decorated service, but the command itself does not need to wrap another command with the same interface.

Chain of responsibility passes a request among handlers, often allowing one handler to consume it or stop traversal. A decorator normally preserves one logical component and delegates through every configured layer. A permission decorator may reject an operation, but if early termination is the system’s main idea, a handler chain may describe the code more honestly.

Adapter changes one interface into another. Decorator preserves the component interface so wrapped and unwrapped objects remain interchangeable.

Pattern names matter less than intent. Use the name that explains why the indirection exists. Future maintainers need to know whether an object replaces behavior, records intent, translates an API, or adds a layer around an existing operation.

Unity-specific assembly choices

Plain C# objects are usually the easiest decorators to test. They do not need to be MonoBehaviour components merely because the game runs in Unity. A MonoBehaviour can own the lifetime of the assembled stack and pass Unity services into it.

Avoid relying on constructors for MonoBehaviour or ScriptableObject instances created by Unity. Use constructors for ordinary C# runtime objects. Use serialized fields, factory methods, OnEnable, or an explicit initialization path for Unity-managed objects, depending on the lifetime involved.

ScriptableObjects are useful as effect definitions shared by many instances. They are assets, however, so mutable per-character state should not quietly live on a shared definition. A poison asset can hold base duration and tick damage. The remaining duration for one enemy belongs in a runtime object.

A small definition might expose a factory method:

public abstract class AttackEffectDefinition : ScriptableObject
{
    public abstract IAttack Wrap(IAttack inner, AttackServices services);
}

An equipment asset can hold an ordered list of definitions. At runtime, the loadout system starts with the base attack and applies each definition in order. This gives designers an editable composition while keeping mutable combat state outside the assets.

There is still a tradeoff. An inspector list makes order editable but does not prove that every order is meaningful. Add validation for known incompatible phases, display the effective order in a debug view, and keep the supported combinations narrower than the theoretical ones.

Debugging a stack should not require archaeology

A wrapper chain hides concrete types behind one interface. That is helpful to callers and occasionally miserable during debugging. A breakpoint on Execute may jump through six wrappers before reaching the base operation. Logs may report the outer type while omitting the rules inside it.

Solve this at the assembly boundary rather than putting reflection into combat code. The factory can record a readable description of the stack for development builds. A debug inspector can show the ordered effect definitions that produced it. Tests can construct known stacks directly.

Do not expose the mutable Inner reference publicly just so arbitrary systems can peel wrappers apart. That breaks encapsulation and creates removal logic that depends on graph surgery. If effects must be added and removed frequently by identity, that is more evidence that the game needs a modifier collection or explicit effect container.

Observability decorators are useful too. A timing or logging layer can surround an operation without polluting the operation itself. Keep such layers out of release builds when their cost is not justified, and avoid logging every call in a hot loop.

Common mistakes

Creating a subclass for each combination anyway

A decorator should reduce combinatorial types. If the project still defines a dedicated assembled subclass for every weapon and effect combination, little has been gained. Put configuration in the composition root or data definitions.

Rebuilding the chain on every operation

Wrappers are normally assembled when configuration changes. Rebuilding them per frame or per attack creates avoidable allocations and repeats work that does not change.

Hiding mandatory rules in optional wrappers

Core invariants should not depend on somebody remembering to attach the correct decorator. If every damage operation must clamp health and respect invulnerability, that belongs in the authoritative damage receiver or another unavoidable boundary.

Letting wrappers own unrelated systems

An attack decorator that directly updates quests, audio, camera shake, achievements, UI, and persistence has become a coordination hub. Return a useful result or publish a narrow event after resolution so those systems can react through their proper boundaries.

Assuming all wrappers commute

Most do not. Multiplication, addition, clamping, conversion, and side effects can produce different outcomes in different orders. Tests should lock down the intended order with concrete values.

Using decorators where a function is enough

A one-off calculation does not need a class hierarchy. A delegate, local function, or direct call may express the same rule with less machinery. Decorator earns its place when the shared interface, recursive composition, and runtime assembly are all useful.

A small test that catches the real risks

The important tests are not “is this class a decorator?” They are behavioral checks for result propagation and order.

For the vampire-blade example, use a fixed random source and actors with known armor. Then verify:

1. a non-critical attack reports and heals from actual damage dealt;
2. a forced critical attack includes the bonus in the outer life-steal calculation;
3. moving life steal inside the critical layer produces the intentionally different result;
4. zero damage produces zero healing;
5. the stack is created once and reused across several attacks.

A compact assertion can document the ordering rule:

IAttack attack = new WeaponAttack(20);
attack = new CriticalAttack(attack, new AlwaysCritical(), 1f, 2);
attack = new LifeStealAttack(attack, 0.25f);

DamageResult result = attack.Execute(new AttackContext(hero, unarmoredTarget));

Debug.Assert(result.Dealt == 40);
Debug.Assert(hero.HealthGained == 10);

That test is more valuable than checking the number of wrapper objects or their inheritance relationships. It fails when a refactor changes combat behavior, which is the risk worth guarding.

When the pattern is the right size

Decorator is a good fit when all of the following are true:

• callers should depend on one stable interface;
• optional behavior belongs before or after one operation;
• layers need to be combined at runtime;
• inheritance would create feature combinations;
• the stack is assembled infrequently compared with how often it runs;
• order can be defined and tested clearly.

Prefer a simpler direct call when there is only one optional rule. Prefer strategy when one implementation replaces another. Prefer a data-oriented modifier collection when effects need identity, duration, sorting, removal, serialization, or rich UI inspection. Prefer a purpose-built pipeline when many ordered stages and early exits are the central design.

The practical takeaway is narrow: decorate operations, not entire game objects. Keep the interface small, compose the stack at a visible boundary, make ordering explicit, and test the result that travels back out. Used that way, decorators remove subclass combinations without replacing them with an invisible maze of wrappers.

References

• Gamma, Helm, Johnson, and Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, “Decorator.”
• Refactoring.Guru: Decorator
• Unity Manual: ScriptableObject
• Game Programming Patterns: Component — useful background on favoring smaller composed domains over a monolithic game-object class.

That is manageable on a small two-dimensional grid. It becomes much less attractive in a genuinely three-dimensional space. A volume that is 256 cells wide, 256 cells deep, and 64 cells high contains more than four million cells before the search has expanded a single node. Most of those cells may describe empty air, yet they still consume memory and enlarge the graph.

An octree attacks the representation problem first. Instead of dividing the whole world into equally sized cells, it keeps large cells where the space is simple and subdivides only where more detail is needed. A hangar can become a handful of large navigable regions while the geometry around beams, doors, and machinery receives finer cells.

A* does not become a different algorithm. It simply searches a smaller, adaptive graph.

Why a uniform 3D grid wastes work

A uniform grid has useful properties. Every cell has the same size, indexing is straightforward, and finding a neighbour is often a small coordinate calculation. Those advantages make grids a strong choice for tile maps and constrained tactical spaces.

The cost is that resolution is global. If a narrow doorway needs half-metre cells, the entire search volume pays for half-metre cells. Large open chambers, empty sky, and long tunnels are all represented with the same density as the doorway.

Doubling resolution along one axis doubles the cell count in two dimensions. In three dimensions it affects the volume. Halving the cell width can produce roughly eight times as many cells because twice as many cells are needed along each of the three axes.

That growth affects more than storage:

• A* may place more nodes in its open and closed sets.
• Building connectivity takes longer.
• Dynamic obstacle updates touch more cells.
• Per-cell clearance, cost, or tactical data consumes more memory.
• Cache behaviour worsens when the search jumps through a large node set.

A better priority queue cannot erase a graph that is unnecessarily large. The strongest optimisation may be to stop creating so many equivalent nodes.

What an octree represents

An octree starts with one axis-aligned cube covering the navigable world. That cube is the root. When the root needs more detail, it is divided into eight equal children: lower and upper halves along the x, y, and z axes.

Each child can be divided again. The process continues until a cell is simple enough to keep or reaches the chosen minimum size.

For navigation, a node commonly receives one of three classifications:

• Free: the volume can be traversed.
• Blocked: the volume cannot be traversed.
• Mixed: it contains both free space and obstacle geometry, so it may need subdivision.

Only the leaves matter to the final navigation graph. A large free leaf represents a large open volume. A cluster of small leaves represents detailed space near geometry. Blocked leaves are omitted from the traversable graph.

This gives the octree its main advantage: spatial resolution follows geometric complexity rather than world size.

The classification test must account for the moving agent, not only point occupancy. A cell that does not intersect a wall may still be too close to the wall for a wide drone. One practical method is to expand obstacles by the agent radius before classifying cells. Another is to store clearance and reject leaves or transitions that do not meet the current agent’s requirements.

The first method produces a graph tailored to one agent size. The second can support several sizes but makes queries and edge validation more involved.

The octree is not yet a pathfinding graph

Subdivision answers where free space exists. A pathfinder also needs connections.

Create a graph node for each traversable leaf, then connect leaves that share a passable boundary. This sounds simple until adjacent leaves have different sizes. One large leaf may touch four or sixteen smaller leaves across one face. A fixed six-neighbour lookup is no longer enough.

A robust edge-building pass needs to answer three questions:

1. Do the leaf bounds touch on a face rather than only at an edge or corner?
2. Does the shared face contain enough open area for the agent to cross?
3. Is the movement valid under the game’s rules for slope, clearance, gravity, and direction?

For a flying agent, any clear shared face may be usable. A walking character usually needs a support surface, acceptable vertical change, and enough headroom. An underwater vehicle may need turning clearance in addition to body clearance.

This distinction matters because “3D pathfinding” covers very different movement models. An octree is a spatial representation, not permission to move freely in every direction.

Neighbour links can be built eagerly after the tree is generated or discovered lazily during search. Eager links make queries cheaper and easier to inspect, but rebuilding them can be expensive when the world changes. Lazy discovery reduces stored edges and can suit sparse queries, but neighbour lookup must be efficient or it simply moves the cost into A*.

Running A* over octree leaves

Once free leaves and valid transitions exist, ordinary A* can search them. The open set still prioritises the node with the smallest estimated total cost:

f(n) = g(n) + h(n)

g(n) is the cost paid from the start. h(n) estimates the cost from the current leaf to the goal.

For free-flying movement with distance-based costs, Euclidean distance between positions is an admissible heuristic. The simplest positions are leaf centres, but centre-to-centre costs can produce awkward routes when cell sizes differ. A route may enter a large cell near one corner and be charged as if it travelled through the centre.

There are several ways to improve this:

• Keep leaf centres for the search, then smooth the resulting route.
• Place transition portals on shared faces and evaluate movement between portals.
• Estimate edge cost from the closest valid points on neighbouring cell bounds.
• Use the centre graph only for the high-level route, then refine movement locally.

The centre-and-smooth approach is a useful starting point. Portal-based search is more precise, especially where large cells meet narrow passages, but it requires more geometry work.

If the heuristic never overestimates the remaining cost, A* retains its optimality guarantee relative to the graph it was given. That final phrase is important. A* can find the cheapest route through an imperfect octree graph and still produce a poor world-space path. Search quality cannot exceed representation quality.

For a fuller explanation of open sets, heuristics, and path reconstruction, see A* Pathfinding: A Practical Guide for Game Developers.

Where the speedup comes from

The useful comparison is not “octree lookup versus array lookup.” Array lookup will often be cheaper.

The octree wins when fewer nodes and edges compensate for more complicated spatial operations. A large free region that would occupy thousands of voxel cells may become one leaf. A* can cross that region in one graph step instead of expanding a wave through every voxel.

Suppose a warehouse contains open air around a few shelves and gantries. A dense voxel graph spends most of its memory proving that empty space is empty. An octree keeps large leaves in the clear volume and refines around shelf edges, the floor, and narrow routes. Search effort becomes concentrated around decisions rather than distance alone.

That does not mean the route should jump directly from the centre of one large cell to another. The graph route identifies a corridor of free leaves. A smoothing or portal pass then finds a better polyline through that corridor.

Three measurements usually reveal whether the representation is helping:

• total traversable leaf count compared with uniform-grid cell count
• nodes expanded per representative query
• end-to-end query time, including neighbour discovery and smoothing

Memory use and rebuild time should be recorded as well. A fast query structure that takes too long to update may be unsuitable for a destructible world.

A practical build pipeline

A navigation octree can be built with a compact recursive process:

Build(cell, depth):
    occupancy = Classify(cell)

    if occupancy is Free:
        emit traversable leaf
        return

    if occupancy is Blocked:
        emit blocked leaf
        return

    if depth == maxDepth:
        apply conservative fallback
        return

    for each of the cell's eight children:
        Build(child, depth + 1)

The conservative fallback normally marks an unresolved mixed cell as blocked. That may remove valid space, but it prevents the pathfinder from routing an agent through geometry the representation could not resolve. If valid passages disappear, the correct response is to increase local resolution or improve classification rather than pretend the cell is free.

After subdivision:

1. collect free leaves
2. build or prepare neighbour lookup
3. locate the leaves containing the start and goal
4. run A* over free leaves
5. reconstruct the leaf corridor
6. convert the corridor to world-space points
7. smooth the points while preserving collision clearance

Keeping these stages separate makes the system easier to profile. It also prevents an expensive smoothing pass from being blamed on the octree search itself.

Finding neighbours without scanning every leaf

The naive neighbour algorithm compares every leaf with every other leaf. It is easy to understand and becomes unusable as the leaf count grows.

The tree already contains the information needed for a better lookup. A face-neighbour query can move upward until it finds an ancestor with space across the requested face, step into the sibling on that side, then descend into children touching the opposite face. The result may be one leaf of the same size, one larger leaf, or a set of smaller leaves.

Another practical option is a hash map keyed by coordinates at the finest resolution. A leaf registers the range or boundary keys it occupies, and a face query retrieves candidates from adjacent keys. This spends extra memory to simplify lookup.

There is no universal winner. Tree-walking keeps the data structure self-contained. Spatial hashing can be easier to debug and faster for frequent queries. Eager adjacency is the simplest runtime option when the octree is mostly static.

Whichever method is chosen, neighbour results should be cached if repeated searches traverse the same static tree. Repeating the same hierarchical lookup for every agent throws away much of the benefit of preprocessing.

Coarse-to-fine search

Searching leaf nodes directly is already adaptive, but the hierarchy can do more.

A coarse-to-fine pathfinder first finds a broad route through higher-level regions, then refines only the parts that need detail. This resembles hierarchical pathfinding on grids: solve the large-scale routing problem before spending time on local geometry.

One approach is to create entrances between sibling regions and search an abstract graph of those entrances. Another is to allow high-level free nodes to participate directly while mixed regions expose lower-level descendants.

The gain is largest in wide worlds with long routes. A path from one end of a space station to the other should not inspect every maintenance duct between them. The high-level search can choose a sequence of sectors, then detailed searches can connect the relevant entrances.

The tradeoff is complexity and path quality. Abstract edges need useful costs. If they ignore local congestion or narrow passages, the high-level route may choose a region that looks short but refines poorly. Start with free-leaf A*. Add another hierarchy only after profiles show that leaf-level searches are still too expensive.

Dynamic obstacles and partial rebuilding

Octrees are often described as ideal for dynamic worlds because branches can be updated independently. That is directionally true, not automatic.

When an obstacle changes, find the affected leaves, reclassify the overlapping region, split cells that became mixed, and attempt to merge sibling leaves that became uniformly free or blocked. Then repair adjacency around the changed boundary.

The merge rule is important. Eight sibling leaves with the same classification can collapse into their parent only if doing so preserves required metadata such as clearance, traversal cost, or ownership. Without merging, repeated edits gradually leave the tree over-subdivided.

Dynamic updates also introduce consistency problems. A query must not traverse half-rebuilt connectivity. Common solutions include:

• rebuilding a small region synchronously before allowing new queries
• swapping in an immutable rebuilt branch
• versioning nodes and rejecting stale paths
• queuing path requests until an update completes

Moving characters should rarely cause structural octree edits. Treating every NPC as permanent blocked geometry creates constant churn and can eliminate routes in crowded spaces. Use local avoidance, reservation systems, or time-aware planning for transient agents. Reserve octree updates for geometry or obstacles that remain relevant long enough to justify rebuilding navigation data.

Path smoothing is not optional polish

An adaptive graph often creates a more obvious need for smoothing than a uniform grid. Leaf centres can zigzag as the path crosses differently sized cells. The route is valid but may look mechanical and travel farther than necessary.

A simple string-pulling pass starts at one waypoint and tests whether a later waypoint can be reached directly. If the swept agent shape stays inside free space, intermediate points can be removed. Repeat until no more points can be skipped.

Use a volume cast or clearance-aware segment test rather than a zero-width ray. A ray can pass through a gap that the agent cannot.

For a corridor represented by shared face portals, a funnel-style algorithm can produce a cleaner path, although a general three-dimensional funnel is less straightforward than its navmesh counterpart. Many games use a simpler compromise: derive candidate points from portals, apply collision-aware shortcutting, and let steering handle small deviations.

Smoothing must use the same agent assumptions as graph construction. If the octree was built for a sphere with radius 0.5 metres, the shortcut test must not validate a centre line with no radius.

Traversal costs still matter

Fewer nodes do not mean all free space is equivalent.

A leaf can carry costs for slope, exposure, terrain, current, noise, or threat. Large leaves need care because one value describes more volume. If a large cell contains meaningful cost variation, it may need subdivision even when it is geometrically free.

This extends the split criterion beyond collision:

split when geometry is mixed
or traversal cost varies too much
or tactical data needs more detail

That creates a navigation structure whose resolution follows decision complexity. A broad, safe chamber can stay coarse. A geometrically open kill zone with strong exposure gradients may need finer leaves so the pathfinder can distinguish the safer edge from the dangerous centre.

This idea connects naturally to layered spatial data. The earlier article Spatial Databases for Tactical AI discusses keeping signals such as visibility, cover, and occupancy separate. Those layers can influence octree subdivision or edge costs without collapsing every concern into the tree itself.

Keep the collision representation authoritative. Tactical layers may adjust preferences, but they should not quietly turn blocked space into a valid route.

A small C# data shape

The runtime node does not need to mirror every build-time detail. A compact leaf record can hold bounds, occupancy, and cached neighbours:

public sealed class OctreeLeaf
{
    public Bounds Bounds { get; }
    public bool IsTraversable { get; }
    public float TraversalMultiplier { get; }
    public IReadOnlyList<OctreeLeaf> Neighbours => neighbours;

    private readonly List<OctreeLeaf> neighbours = new();

    public OctreeLeaf(
        Bounds bounds,
        bool isTraversable,
        float traversalMultiplier = 1f)
    {
        Bounds = bounds;
        IsTraversable = isTraversable;
        TraversalMultiplier = traversalMultiplier;
    }

    public void Connect(OctreeLeaf other)
    {
        if (!IsTraversable || !other.IsTraversable || other == this)
            return;

        if (!neighbours.Contains(other))
            neighbours.Add(other);
    }
}

Production code may store indices instead of object references for denser memory and better cache behaviour. The important boundary is conceptual: subdivision builds leaves, connectivity validates transitions, and A* consumes the resulting graph. Keeping those jobs distinct makes each one testable.

At minimum, tests should cover:

• a completely free root that remains one leaf
• a blocked root with no traversable node
• a mixed root that subdivides
• a large leaf connected to several smaller leaves across one face
• a narrow opening rejected for an oversized agent
• an update that splits and later merges the same branch
• a path whose smoothed segments retain clearance

The unequal-neighbour case deserves special attention. Many octree navigation bugs hide there because same-size cells work correctly during early prototypes.

When octrees are the wrong choice

Octrees are useful when the world is volumetric, sparse, and unevenly detailed. Flying agents, underwater vehicles, zero-gravity movement, voxel caves, and large destructible volumes are natural candidates.

They are less compelling when movement is constrained to surfaces. A navmesh usually represents walkable floors more directly and produces better paths with fewer special rules for support and slopes. A two-dimensional grid may be simpler for a tactics game whose height differences are discrete. A waypoint graph may be enough for a small authored level.

Octrees also lose some appeal when the environment is dense at every scale. If almost every cell remains mixed until the maximum depth, the tree approaches the leaf count of a uniform voxel grid while retaining more complicated neighbour logic and pointer overhead.

The decision should be driven by measurements from representative levels:

1. Build a simple uniform baseline.
2. Record memory, build time, node count, expansions, and query latency.
3. Build the octree at equivalent minimum clearance.
4. Include neighbour lookup and smoothing in the timing.
5. Test short, long, open, narrow, and unreachable routes.
6. Test representative world updates if geometry changes at runtime.

If the octree reduces expansions but total query time rises, neighbour discovery or memory layout may be the actual bottleneck. If queries are fast but updates hitch, partial rebuilding needs attention. If paths cut corners, the problem is likely transition validation or smoothing rather than A*.

Practical takeaway

Octrees optimise 3D pathfinding by reducing the graph before the search begins. Open volumes become large leaves. Detailed geometry receives small leaves. A* then spends its effort around obstacles and route choices instead of expanding thousands of equivalent empty voxels.

The design succeeds when four details are handled carefully:

• free leaves are classified for the agent’s real volume
• neighbours across unequal cell sizes are connected correctly
• edge costs and heuristics match the movement model
• the leaf corridor is converted into a clearance-safe world-space path

Start with leaf-level A*, cached adjacency, and collision-aware smoothing. Measure that version before adding coarse-to-fine abstractions or highly dynamic rebuilding. The octree already provides the largest structural gain: it lets simple space stay simple.

An NPC behind a building runs the same animation graph as one standing in front of the camera. A distant ambient effect keeps updating. Every possible spawn point checks its surroundings. Hundreds of world markers measure their distance from the player in separate Update methods.

None of those decisions is individually disastrous. Their combined cost is.

Unity’s CullingGroup API offers a useful middle ground between doing nothing and replacing the whole project with a custom spatial database. Give it bounding spheres, a camera, and a set of distance thresholds. Unity then reports when each sphere changes visibility or moves into another distance band. Gameplay code can use those changes to select a cheaper level of simulation.

The important correction is that CullingGroup does not manage objects. It supplies coarse visibility and distance information. The game still decides what “cheap,” “dormant,” and “visible” mean.

Culling renderers is only half the job

Unity already avoids drawing many objects outside the camera frustum. Static occlusion culling can also reject renderers hidden behind baked occluders. That saves rendering work, but it does not automatically settle every gameplay cost attached to those objects.

A disabled renderer does not imply that an AI planner, animation controller, IK pass, audio emitter, or custom Update method has stopped. Those systems have different correctness rules. An off-screen guard may still need to hear a sound. A distant animal may only need a cheap movement approximation. A hidden spawn point may be especially useful because spawning there will not visibly pop an enemy into existence.

This is where CullingGroup fits. It exposes information from Unity’s culling pipeline so non-rendering systems can make deliberate budget decisions too.

Typical uses include:

• reducing animation and AI quality for distant crowds
• pausing cosmetic effects when their area is not visible
• finding hidden spawn locations
• waking world objects when the player approaches
• replacing hundreds of per-object distance checks with one grouped query
• keeping only a lightweight data representation for distant agents

This is not a promise that every use will be faster. It is a way to move repeated visibility and proximity work into a purpose-built engine facility, then respond only when state changes.

The data model is intentionally coarse

A culling group works with an array of BoundingSphere values. Each sphere has a center and radius. There are no boxes, capsules, meshes, or arbitrary volumes.

That limitation is useful. A sphere is cheap to test and has no orientation. The tradeoff is an approximate fit. A tall building enclosed by one large sphere may count as visible when only empty space around its corners intersects the view. A long train may need several spheres if one enclosing sphere is too loose.

The group calculates two related results for every active sphere:

1. Visibility relative to one target camera.
2. A distance band relative to one reference point.

Visibility uses camera-frustum culling and static occlusion-culling information. Unity’s documentation is explicit that dynamic objects are not considered as occluders. A truck driving between the camera and an NPC does not make that NPC hidden as far as this API is concerned.

Distance is measured from the reference point to the closest point on the sphere, not simply to its center. Unity does not return the raw distance. It compares the result with thresholds supplied by the game and returns a discrete band.

Given thresholds of 20, 60, and 120 metres, the bands can be interpreted as:

• band 0: close
• band 1: medium
• band 2: far
• beyond the last threshold: outside the managed range

That quantization is a feature, not missing precision. Most gameplay budgeting does not need to know that an agent is exactly 47.38 metres away. It needs to know that the agent crossed from “full simulation” into “reduced simulation.”

Pick budgets before writing callbacks

The API is easier to use when the policy is defined first. Otherwise every callback grows a collection of unrelated toggles and exceptions.

A practical crowd policy might look like this:

The exact table depends on the game. Multiplayer authority, audio propagation, combat, and deterministic simulation can all require work that visibility alone cannot switch off.

The useful pattern is to separate simulation significance from presentation visibility. Distance is often a reasonable input to simulation quality. Camera visibility is often a reasonable input to animation, particles, and other presentation work. Combining both into one SetActive(false) call is tempting and usually wrong.

A small working setup

The following component owns one culling group for a fixed set of agents. It updates sphere positions in LateUpdate and sends state changes back to each agent.

using UnityEngine;

public sealed class AgentCullingController : MonoBehaviour
{
    [SerializeField] private Camera targetCamera;
    [SerializeField] private Transform distanceReference;
    [SerializeField] private CullableAgent[] agents;
    [SerializeField] private float sphereRadius = 1.5f;
    [SerializeField] private float[] distanceBands = { 20f, 60f, 120f };

    private CullingGroup group;
    private BoundingSphere[] spheres;

    private void OnEnable()
    {
        if (targetCamera == null)
            targetCamera = Camera.main;

        if (targetCamera == null)
        {
            Debug.LogError("AgentCullingController needs a target camera.", this);
            enabled = false;
            return;
        }

        spheres = new BoundingSphere[agents.Length];
        for (int i = 0; i < agents.Length; i++)
            spheres[i] = new BoundingSphere(agents[i].transform.position, sphereRadius);

        group = new CullingGroup
        {
            targetCamera = targetCamera,
            onStateChanged = OnStateChanged
        };

        group.SetBoundingSpheres(spheres);
        group.SetBoundingSphereCount(spheres.Length);
        group.SetBoundingDistances(distanceBands);
        group.SetDistanceReferencePoint(
            distanceReference != null ? distanceReference : targetCamera.transform);
    }

    private void LateUpdate()
    {
        // CullingGroup keeps a reference to this array, so changing entries is enough.
        for (int i = 0; i < agents.Length; i++)
            spheres[i].position = agents[i].transform.position;
    }

    private void OnStateChanged(CullingGroupEvent evt)
    {
        agents[evt.index].ApplyBudget(evt.isVisible, evt.currentDistance);
    }

    private void OnDisable()
    {
        if (group == null)
            return;

        group.onStateChanged = null;
        group.Dispose();
        group = null;
    }
}

There are a few details worth keeping.

SetBoundingSpheres does not copy the array. The group retains a reference to it. Updating an existing sphere’s position therefore does not require calling SetBoundingSpheres again. This is both convenient and a reason not to replace or lose the array casually.

SetBoundingSphereCount tells Unity how much of the allocated array is active. The backing array can be larger than the current count. Unity recommends reserving enough capacity to avoid resizing at runtime, which is valuable for crowds and pooled objects.

The distance reference can be a Transform. That makes a player or camera rig a sensible source without manually pushing a new vector every frame. One group supports one reference point and one camera.

Finally, the group implements IDisposable. Creating it in OnEnable and disposing it in OnDisable gives the native resource an explicit lifetime. Skipping disposal is not an acceptable shortcut.

Keep the receiver boring

The receiver should apply a policy, not rediscover visibility. Here is a deliberately small example:

using UnityEngine;

public sealed class CullableAgent : MonoBehaviour
{
    [SerializeField] private MonoBehaviour expensiveAi;
    [SerializeField] private Animator animator;
    [SerializeField] private ParticleSystem cosmeticEffect;

    public void ApplyBudget(bool cameraVisible, int distanceBand)
    {
        // Close and medium agents can think; farther agents use a cheaper world model.
        if (expensiveAi != null)
            expensiveAi.enabled = distanceBand <= 1;

        // Presentation only matters when the camera can see it.
        if (animator != null)
            animator.enabled = cameraVisible && distanceBand <= 1;

        if (cosmeticEffect == null)
            return;

        bool shouldPlay = cameraVisible && distanceBand == 0;
        if (shouldPlay && !cosmeticEffect.isPlaying)
            cosmeticEffect.Play();
        else if (!shouldPlay && cosmeticEffect.isPlaying)
            cosmeticEffect.Stop(true, ParticleSystemStopBehavior.StopEmitting);
    }
}

This is an example policy, not a universal agent controller. Disabling an Animator can leave a character frozen in its current pose. That may be fine for an invisible agent but wrong when it becomes visible again, especially if root motion owns the transform. Disabling an AI behaviour may also discard timing assumptions.

Production code often replaces the booleans with explicit tiers such as Full, Reduced, PresentationOnly, and Dormant. Each subsystem can then decide what a tier means. The culling controller reports state; it does not become the owner of animation, AI, networking, and effects.

Callbacks are delayed state, not an immediate physics query

One of the easiest mistakes is to move a sphere and immediately ask the group for its new result.

Culling data is updated when Unity performs culling for the target camera. Until that happens, IsVisible, GetDistance, callbacks, and bulk query results describe the latest completed culling pass. Unity’s manual recommends treating the API asynchronously for this reason.

That has two consequences.

First, do not use CullingGroup for correctness decisions that require an answer at an exact instant. A melee hit test, line-of-sight shot, or security check needs physics, geometry, or authoritative game state. Camera culling is not a substitute.

Second, callbacks should tolerate a frame of delay. Simulation budgeting, effect control, crowd detail, and spawn-site filtering usually can. If a one-frame delay breaks the feature, the feature probably needs a different query.

The onStateChanged callback is efficient because it only reports transitions. It receives a CullingGroupEvent containing the sphere index, previous and current distance bands, visibility, and convenience flags such as hasBecomeVisible and hasBecomeInvisible.

Use those transition fields when setup and teardown differ:

private void OnStateChanged(CullingGroupEvent evt)
{
    if (evt.hasBecomeVisible)
        agents[evt.index].PreparePresentation();

    if (evt.hasBecomeInvisible)
        agents[evt.index].ReleasePresentation();

    if (evt.previousDistance != evt.currentDistance)
        agents[evt.index].SetSimulationBand(evt.currentDistance);
}

Heavy work should still be deferred. Loading an asset, instantiating a complex prefab, or rebuilding navigation state directly inside a burst of callbacks can merely move the hitch. Queue expensive transitions and process a limited number per frame.

Queries are useful when transitions are not enough

Callbacks are the normal choice for persistent state. Sometimes a system needs a snapshot instead.

A spawn director may ask for currently hidden candidates. A debug overlay may need every sphere in a particular distance band. A streaming controller may periodically reconcile its active set.

For those cases, the API provides IsVisible(index), GetDistance(index), and several QueryIndices overloads. A bulk query fills a caller-provided integer array with matching sphere indices.

private readonly int[] hiddenCandidates = new int[256];

private int FindHiddenCandidates(CullingGroup group)
{
    return group.QueryIndices(false, hiddenCandidates, 0);
}

The result buffer sets the maximum returned by that call. If more matches exist than the buffer can hold, continue from a later starting index or use a larger reusable buffer. Do not allocate a fresh array every time a spawn decision runs; that would turn a culling optimization into managed allocation churn.

Queries still return the last completed camera-culling results. They do not force an update.

Dynamic sets need stable ownership of indices

A fixed inspector array is enough for the first implementation. Pooled enemies, procedural props, and streaming worlds need registration and removal.

The sphere index becomes the identity passed through every event, so there must be a matching index-to-object table. A compact array or list works well. On removal, swap the final active entry into the removed slot, update both the sphere and object entry, reduce the active count, and call SetBoundingSphereCount.

That avoids shifting a large tail of elements:

remove index 3
move last active sphere and owner into index 3
decrement active count
update SetBoundingSphereCount(activeCount)

If outside code stores culling indices, the swap must also update that object’s stored handle. Better yet, keep indices private to the manager and expose an opaque registration handle.

There is one awkward edge case: a state-change event may already be pending for an index that is being recycled. A generation counter on each slot can prevent stale work from being applied to a newly registered object. Smaller projects can avoid that machinery by batching registration changes at a known point in the frame, after processing culling events.

Do not build a general-purpose handle allocator before the project needs dynamic membership. Start with a fixed set, measure the result, and add slot management when pooling or streaming makes it necessary.

One camera and one reference point are real constraints

A single CullingGroup evaluates one camera and one distance reference point. Split-screen, security cameras, minimap cameras, scene views, and spectator cameras complicate the policy.

Unity recommends using one group per camera when visibility must be evaluated from multiple cameras. Those groups can share the same bounding-sphere array because the array is referenced rather than copied. The game must then combine results, usually treating an object as visible if any relevant gameplay camera sees it.

Be careful about cameras that do not represent a player. A minimap camera should not necessarily wake full animation or AI across the whole map. Define which cameras participate in which budget decisions.

Distance has the same issue. A local co-op game may need the minimum band across two players, but one group only accepts one reference. Multiple groups or a separate distance system may be clearer.

At that point, a spatial hash, quadtree, ECS-based solution, or jobified distance pass can become the better tool. CullingGroup is valuable because it is narrow. Trying to hide its constraints behind a sprawling framework removes much of that value.

Common mistakes

Treating visibility as line of sight

Frustum and static occlusion results are not gameplay perception. Dynamic occluders are ignored, and an enclosing sphere is only an approximation. Use physics or a purpose-built visibility system when an AI must know whether it can actually see a target.

Deactivating the whole GameObject

SetActive(false) can stop scripts needed to wake the object, interrupt coroutines, alter pooling lifecycle, and disable colliders that remain important to gameplay. Disable or reduce expensive subsystems deliberately. If a fully dormant object must disappear, keep its lightweight record in a manager that remains active.

Updating every policy every frame

The point of onStateChanged is to react to transitions. Reapplying the same animation, AI, and particle settings each frame adds work and can restart systems accidentally.

Allocating exact-size arrays repeatedly

Reserve sphere capacity and reuse query result buffers. SetBoundingSphereCount exists so array capacity and active count can differ.

Using tiny distance thresholds without hysteresis

An object hovering around a threshold can bounce between bands. CullingGroup does not turn a noisy policy into a stable one. Choose bands with meaningful spacing, and add delayed promotion or hysteresis in the receiving policy when transitions trigger expensive work.

Assuming the callback is free

The visibility calculation may be grouped, but callback code still runs. A thousand objects crossing a threshold together can create a spike if each callback starts effects, allocates data, or loads content. Budget the transitions as carefully as the steady state.

Measure the result that matters

The success metric is not “fewer active GameObjects.” It is frame time and frame-time stability on target hardware.

Profile before and after with a representative scene. Look at script update time, animation, particles, rendering, and garbage collection. Test a camera cut or teleport that makes many spheres change state at once. Walk back and forth across distance thresholds. Verify split-screen and secondary-camera behaviour if they exist.

Also test correctness:

• Can off-screen AI still affect gameplay when required?
• Do agents resume in a valid state?
• Does an effect restart cleanly?
• Can an inactive spawn point become eligible?
• Are networked objects still simulated by the authority?
• Does a camera teleport produce a transition storm?

A culling policy that saves a millisecond but causes guards to forget the player is not an optimization. It is a gameplay bug with a good profiler screenshot.

Practical takeaway

Use CullingGroup when many objects need the same coarse answer: whether a camera can potentially see them and which distance tier they occupy.

Keep one owner for the group, its sphere array, and the index-to-object mapping. Reserve capacity, update sphere positions without replacing the array, react to state changes instead of polling every object, and dispose the group with its owner. Let distance choose simulation quality and visibility choose presentation where that split matches the game.

Most importantly, treat the result as a budget signal rather than truth. It is not line of sight, physics, networking authority, or exact distance. It is a cheap way to stop spending full price on objects the player cannot currently notice.

That narrow job is enough to make it useful.

References

• Unity Manual: Introduction to the CullingGroup API
• Unity Manual: Create a Culling Group
• Unity Manual: Get culling results
• Unity Scripting API: CullingGroup
• Unity Scripting API: CullingGroupEvent
• Unity Scripting API: CullingGroup.QueryIndices

The newer Unity CLI points at a better shape. The official docs describe it as “a standalone command-line tool for installing and managing Unity Editors and modules from a terminal.” That matters because the tool is separate from the desktop Hub experience, and because it starts to put common Unity workflow chores behind named commands: install an Editor, add modules, open a project, run tests, build a player, inspect the machine, and talk to a connected Editor.

One naming caveat belongs up front. Unity’s current documentation calls the tool Unity CLI, not “Unity Core CLI.” That title is still useful as a human label for the kind of thing Unity developers have wanted: a core terminal surface for daily Unity work. It should not be confused with the Unity Gaming Services CLI, and it is not the same thing as the older Unity Editor command-line argument page. The tool is also marked experimental in the docs, so exact syntax should be checked against unity --help on the installed version before turning any of this into production automation.

With that caveat in place, there are five areas that look genuinely useful for Unity teams.

1. Scriptable Editor and module installation

The first feature is the least glamorous, which is usually why it matters. Installing the right Unity Editor version on a fresh machine should not be a ceremony. A developer workstation, a CI runner, a build VM, and a temporary test box all need the same basic ingredients: a specific Editor version and the modules required by the target platforms.

Historically, that often meant using Unity Hub manually, scripting around Hub, or baking large machine images that go stale. The Unity CLI gives that workflow a cleaner terminal surface:

unity install lts
unity install 6000.3.7f1
unity install 6000.3.7f1 -m android --cm
unity install lts -m ios android webgl
unity install-modules -e 6000.3.7f1 -m ios android
unity editors -i

There are a few details in that small command set that are easy to understate. Version aliases such as lts, latest, and major/minor streams make scripts less tied to a hardcoded patch version when that is what the workflow wants. Exact versions still exist for reproducible agents and release branches. Modules can be added at install time or later with install-modules. The --cm or --childModules option is there for cases such as Android, where the module is not useful unless the SDK and NDK pieces come along for the ride.

That is a better division of labor. The build script should declare what it needs. The machine should be able to become that machine from a terminal. The person reading the script should not have to know which Hub screen would have been clicked.

For teams that maintain multiple Unity versions, unity editors -i and unity editors default [version] are also useful because they make installed Editor state visible. A broken CI machine often starts with something boring: the wrong Editor version, a missing platform module, or a default Editor pointing at an older install. The sooner that state can be listed and checked by a script, the less time gets wasted reading a 20,000-line Unity log.

The best version of this feature is not a fancy one-click setup. It is a boring bootstrap script that a new runner can run without a human sitting beside it. Unity projects have enough moving parts already. Editor installation should not be one of the mysterious ones.

2. Build and test commands that read like the job

The second feature is the one most CI setups will notice first. Unity automation usually ends up with a wrapper script named after the thing the team wanted in the first place: build, test, smoke test, export Android, run Edit Mode tests. The wrapper calls Unity in batchmode, invokes a project method, and maps the result back into whatever CI system is watching.

A CLI command named unity build or unity test is a cleaner starting point:

unity open ./MyProject
unity build
unity test
unity run

A named command does not remove the need to understand Unity’s build pipeline. It does remove some of the accidental complexity around reaching it. When the CLI owns the verb, it can own the boring behavior that every team otherwise has to rediscover: consistent flags, predictable output, better exit codes, and CI-friendly defaults.

The build provenance work is the part worth watching. Unity’s release notes describe a provenance manifest written next to build output, recording the Editor version, resolved package set, build target, Git revision, and timestamps. The notes also say the manifest is written for failed builds and leaves out paths, credentials, and machine-identifying details.

That is exactly the kind of artifact a build should leave behind. A failed build without provenance is a mystery. A passed build without provenance is only slightly better, because the team still has to answer what was actually built. The useful question is not only “did it pass?” The useful question is “what ingredients produced this result?”

Test support is also moving in the right direction. The documented and release-note surface includes unity test, NUnit report output, sharding with --shard N/M, retries with --retries N, and failed-test reruns with --rerun-failed. Those features sound mundane until a project has thousands of Play Mode and Edit Mode tests fighting for time on shared runners.

Sharding matters when a single test job becomes the longest pole in the pipeline. Retries matter when the team is separating real failures from a small number of flaky tests. Rerunning failed tests matters because it can produce a tighter signal than rerunning everything. None of those features make bad tests good. They do give the pipeline a more practical set of controls.

Exit codes are part of the story too. The reference docs distinguish test failures from other operation failures. Exit code 8 is used when tests ran and one or more failed; exit code 6 covers cases where the primary operation failed or a build/test run did not finish. That distinction lets CI report a failed test suite differently from a broken runner, missing license, or crashed Editor. A small difference, but small differences are what make automation trustworthy.

3. Output formats and diagnostics that belong in CI

Unity logs are useful, but they are not an API. A human can read them. A script can grep them. Neither of those is the same as a command-line tool promising machine-readable output.

The Unity CLI docs list several output formats:

unity editors -i --format json
unity editors -i --format tsv
unity install lts --format ndjson
unity install lts --format github

The shape matters. human output is for terminals. tsv is useful when output is piped or saved. json gives a structured envelope with fields such as success, command, data, errors, and warnings. ndjson works better for long-running commands because progress can be emitted as a stream of JSON objects. github maps messages into GitHub Actions annotations like ::error:: and ::warning::.

That sounds like normal CLI behavior because it is. Unity getting closer to normal CLI behavior is the point.

A good CI command should be quiet when asked, structured when piped, and explicit when it fails. The docs also call out environment variables such as UNITY_FORMAT, UNITY_QUIET, UNITY_NO_BANNER, UNITY_NON_INTERACTIVE, UNITY_PROJECT_PATH, and UNITY_BUILD_TIMEOUT. Those knobs are useful because CI configuration often wants policy outside the command itself. A job can set UNITY_NON_INTERACTIVE once, then every Unity CLI call in that job inherits the rule.

The diagnostic commands are the other half:

unity doctor
unity doctor --ci
unity cache key
unity env
unity logs
unity diagnose

unity doctor --ci is the standout. The release notes describe it as checking whether a machine can finish a build or test run, including license, required Editor, disk space, and network reachability. That is the kind of command a pipeline should run before spending twenty minutes starting a build that had no chance of completing.

unity cache key is another practical detail. A Unity Library cache is only useful when the key matches the things that make the cache valid. The release notes say the key is derived from the Editor version, resolved package set, and build target. That is the right neighborhood. A cache key based only on branch name or commit hash tends to be either too broad or too narrow. A Unity-aware key gives the CI system a better chance of avoiding stale imports without throwing away every cache.

The exit-code table also helps automation. A retryable Unity service failure can be treated differently from a usage error. A configuration-required error can point the maintainer toward setup instead of source changes. A SIGTERM from the runner should not be reported as a Unity test failure. These distinctions are boring until the night a release build fails and the only message is “process exited with code 1.”

4. Version-control commands that understand Unity projects

The version-control commands may be the most Unity-specific part of the CLI. Generic Git can tell a team which files changed. It cannot always explain what those changes mean inside a Unity project.

Unity projects carry their own version-control problems: .meta files, GUID pairing, scene and prefab YAML, Git LFS for binary assets, UnityYAMLMerge setup, branch switching that triggers expensive reimports, and pull requests where the meaningful change is hidden behind file IDs.

The CLI’s vcs surface points directly at those pain points:

unity vcs status
unity vcs doctor --fix
unity vcs merge-setup
unity vcs diff Assets/SomePrefab.prefab
unity vcs affected
unity vcs switch feature/some-branch
unity vcs git migrate-lfs

This is where a Unity-aware tool can beat a generic script. unity vcs status can group changes by Unity meaning and identify .meta pairing problems. A missing or mismatched .meta file is not just another changed file; it can break references across the project. Catching that early is worth more than a prettier status view.

unity vcs merge-setup is another useful example. Scene and prefab merges are painful enough without each developer configuring the merge tool differently. A one-command setup for UnityYAMLMerge lowers the odds that two machines treat the same conflict in two different ways.

The diff command is the one that sounds most useful for code review. A normal prefab diff often exposes fileID noise and YAML structure before it exposes the thing a reviewer cares about. The release notes describe unity vcs diff <path> as reading scene and prefab changes by GameObject and component name instead. That is a much better review unit. A reviewer wants to know which component changed, not decode serialized object trivia by hand.

unity vcs affected could become useful in larger projects. If a change can report which prefabs, scenes, assets, or tests are impacted, teams can make better choices about targeted validation. It will not replace full test runs before release, and it should not become an excuse to skip broad checks. But as a local or pull-request signal, “what did this change probably touch?” is a question Unity is better positioned to answer than plain Git.

There is also practical value in unity vcs switch <branch> reporting expected reimport cost before switching. Anyone who has bounced between large Unity branches knows the pain: a small code review can turn into an import penalty because asset state changed under the project. A warning does not remove the cost, but it lets the developer make an informed choice instead of discovering it after the switch.

This section deserves the largest caveat. Much of this VCS surface appears in recent beta release notes, and the whole CLI is experimental. It should be treated as promising, not as a settled contract. Still, it is the right kind of promise: Unity-specific automation for Unity-specific version-control problems.

5. Connected Editor automation through Pipeline, commands, eval, and MCP

The fifth feature points beyond CI. Installing Editors and running builds are obvious automation targets. The more interesting daily workflow is what happens when the CLI can talk to a running Editor.

Unity’s Pipeline package is described as a way to “Control the Unity Editor remotely through a local HTTP API to automate builds, tests, and development workflows.” The documented flow starts with authentication, then installing and listing the Pipeline package:

unity auth login
unity pipeline install
unity pipeline list

Once the Editor is connected, the CLI surface includes commands such as:

unity status
unity list
unity command
unity command <name>
unity command <name> --detach
unity eval <expr>
unity job status
unity job wait
unity job cancel

That shape is interesting because it gives tooling a path into the Editor without pretending the Editor is not there. Some Unity work belongs inside the Editor process. Asset database operations, project-specific menu commands, certain validation steps, and custom tools often need the actual project context. The older answer was usually another -executeMethod wrapper or an editor script wired into a menu item. A connected command surface could make those jobs easier to discover and easier to run.

unity list is a small command with a big implication: list every tool a connected Editor registers, with parameter schema. That gives local tools and AI agents a way to ask “what can this project do?” instead of relying on tribal knowledge. It also nudges teams toward named, registered operations instead of one-off scripts hidden in a folder.

The MCP angle is worth mentioning carefully. Unity’s docs say the MCP server included in the in-Editor AI assistant package has been deprecated, and that the unity mcp command in Unity CLI replaces it. They also say unity command and unity eval drive the Editor directly without MCP, and that those direct commands are faster and use fewer tokens than MCP for that job.

That is the right framing for most developers. MCP is useful when an agent needs a tool protocol. Direct CLI commands are better when a script already knows what it wants. The exciting part is not “AI can now touch Unity.” The exciting part is that Unity appears to be defining a clearer local automation boundary: install the Pipeline package, expose commands from the Editor, call them from a terminal, and manage detached jobs when the work takes time.

For teams building custom validation tools, content checks, import audits, or one-button release chores, this could be the difference between a tool that only works from one developer’s menu bar and a tool that works from a terminal, a CI job, or an agent with the same command name.

A measured caveat: experimental means verify before depending on it

The reason to be excited is not that every command listed above should be dropped into production today. The official docs mark Unity CLI as experimental, and several of the most interesting pieces are described in beta release notes. That means two habits are mandatory.

First, check the installed CLI, not only the web docs:

unity --help
unity build --help
unity test --help
unity vcs --help

The docs themselves point developers toward unity --help as the source that matches the installed version. That matters for beta tooling. A blog post, CI template, or team wiki can go stale faster than the command line installed on the runner.

Second, introduce the CLI at the edges before making it the foundation of the whole pipeline. Editor installation on a disposable runner is a good early target. unity doctor --ci before an existing build is another. Structured output for one inspection command is low risk. Replacing every build, test, VCS, and Editor automation script at once is how a promising tool becomes tomorrow’s outage.

There is also a naming risk. “Unity Core CLI” is not the official documentation label found during research. The article title can keep that phrase because it describes the idea people are reacting to: a central command-line layer for Unity work. The body should use Unity’s own name, Unity CLI, so readers can find the docs and avoid mixing it up with Unity Gaming Services CLI or older Editor arguments.

The useful posture is cautious optimism. Unity teams already script these jobs. They already install Editors on runners, run tests in batchmode, parse logs, configure YAML merge, manage Library caches, and call custom Editor commands. The Unity CLI is exciting because it names those jobs directly. If it keeps moving in this direction, the terminal can become less of a workaround and more of a supported part of the Unity workflow.

References

• Unity CLI overview: https://docs.unity.com/en-us/unity-cli/unity-cli.md
• Install and use Unity CLI: https://docs.unity.com/en-us/unity-cli/use-unity-cli.md
• Unity CLI command reference: https://docs.unity.com/en-us/unity-cli/unity-cli-reference.md
• Unity CLI release notes: https://docs.unity.com/en-us/unity-cli/release-notes.md
• Unity Pipeline package: https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-pipeline-package.md
• Replacing the deprecated in-Editor MCP server with Unity CLI: https://docs.unity.com/en-us/unity-cli/replace-mcp-server-unity-cli.md

That sounds small, because it is. Records are not a new way to build every gameplay object. They are not a replacement for MonoBehaviour, ScriptableObject, serialized inspector data, mutable services, or performance-sensitive simulation state. They are a language feature for value-shaped data: data where two instances with the same contents should usually be treated as equal.

That narrow definition is what makes records useful in Unity. The trouble starts when the feature gets dragged outside that shape.

A Unity project already has several kinds of data living together. Some data is authored in the inspector. Some data moves through runtime systems as commands, events, snapshots, or requests. Some data belongs to live scene objects with identity, lifetime, references, and mutable state. A record can make the middle group cleaner. It usually makes the first and third groups worse.

The practical rule is simple: use records after a boundary, not as the boundary itself. Let Unity serialize boring authoring data. Convert that data into compact runtime values when value semantics help. Keep live gameplay objects as normal objects with identity and behavior.

What a record buys you

A normal C# class compares by reference unless it overrides equality. Two instances can contain the same values and still be considered different objects because they are different allocations. That is often correct. A player, enemy, projectile, UI widget, or service is not the same thing as another object just because some fields match.

For data messages, reference equality is often noise.

public sealed record DamageRequest(
    EntityId Source,
    EntityId Target,
    int Amount,
    DamageType Type);

var hit = new DamageRequest(attackerId, targetId, 25, DamageType.Fire);
var criticalHit = hit with { Amount = 50 };

DamageRequest is a good record candidate because it describes a thing the game should process. It is not the attacker. It is not the target. It is not a component with a lifetime. It is a value-shaped request: source, target, amount, type.

A record class gives you value-based equality, generated members, a useful ToString, deconstruction support when you use positional syntax, and with expressions for copying with a changed field. Those features are handy in tests, logs, command queues, editor tools, import pipelines, and glue code between systems.

The generated equality is the main signal. If two requests contain the same source, target, amount, and damage type, treating them as equal probably makes sense. If that sentence sounds wrong for a type, the type probably should not be a record.

Unity objects are identity-shaped

Most live Unity objects are not value-shaped.

A player object is not equal to another player object because both have 100 health. A projectile instance is not equal to another projectile because both came from the same prefab. A MonoBehaviour is a component attached to a scene object. A ScriptableObject is often an asset with editor identity, references, import behavior, and shared usage across scenes.

Those objects exist somewhere. They have identity.

Records describe something. That difference matters more than the syntax.

Identity-shaped                      Value-shaped
---------------                     ----------------
PlayerController                    DamageRequest
Enemy MonoBehaviour                 SpawnCommand
InventoryService                    StatSnapshot
WeaponDefinition asset              MatchmakingOptions
Quest ScriptableObject              SaveMigrationStep

The left side owns behavior, lifetime, engine references, or shared state. The right side moves facts across a boundary. Records belong mostly on the right side.

This is not a purity rule. Game code should not care about language-feature purity. The point is to avoid misleading defaults. A record says equality is based on contents. A scene object usually says equality is based on identity. If the type’s meaning disagrees with the generated behavior, the generated behavior is working against the code.

Do not use records as Unity serialized data by default

Unity serialization is not a general-purpose .NET serializer. It has its own supported field shapes, object-reference behavior, prefab override rules, domain reload behavior, editor display assumptions, and asset persistence model. Records were designed for C# data modeling, not for Unity’s serialized object graph.

Unity’s documentation calls out record caveats directly, including serialization concerns. The safe default is to keep records out of serialized fields unless the exact Unity version and serialization path have been tested.

This is fine:

public sealed record InventoryChange(ItemId Item, int Delta);

public sealed class InventorySystem
{
    public void Apply(InventoryChange change)
    {
        // Runtime message. Unity does not serialize this object.
    }
}

This is where the risk starts:

public sealed class LootTable : MonoBehaviour
{
    [SerializeField] private DropRule defaultRule;
}

public sealed record DropRule(ItemId Item, float Weight);

The second version puts a record directly into Unity’s serialized object graph. Now inspector display, prefab overrides, generated members, init accessors, field rules, and Unity version support all have to line up. Some teams can make a specific version of that work. It is still the wrong default for a shared project unless there is a clear reason and a test around it.

For inspector data, boring code is usually better:

[Serializable]
public sealed class DropRuleData
{
    public ItemDefinition item;
    public float weight;
}

Then convert the authoring data into a runtime value after validation:

public sealed record DropRule(ItemId Item, float Weight);

public static DropRule ToRuntime(DropRuleData data)
{
    return new DropRule(data.item.Id, data.weight);
}

That conversion is not ceremony for its own sake. It gives each side the shape it wants. Unity gets inspector-friendly fields. Runtime code gets a compact value object. Designers do not have to care how records work, and gameplay systems do not have to drag inspector concerns through every method signature.

init support and language versions can still bite

Records are tied to newer C# language features. In modern .NET, the compiler and runtime provide the pieces records expect. Unity moves differently. A Unity version can support a particular C# language level while still having caveats around generated code, runtime profiles, IDE support, and build targets.

Older Unity setups that use record syntax may require an IsExternalInit compatibility shim:

namespace System.Runtime.CompilerServices
{
    internal static class IsExternalInit { }
}

That shim is not scandalous. It is also not a license to spread records through the project. If the project needs it, put it in one obvious file, comment why it exists, and remove it when the Unity/runtime combination no longer needs it.

The boring check is the important one: the project has to compile in CI, on teammate machines, and for the target platforms. A language feature that only works in one local editor setup is not saving time. It is turning a small syntax win into a build-system problem.

This matters even more for record struct. C# 10 added record structs, but Unity language-version support depends on the Unity version and project setup. A post can show the syntax. A production project has to compile it.

public readonly record struct StatSnapshot(
    int Health,
    int Armor,
    float MoveSpeed);

If the toolchain supports it, a small readonly record struct can be a clean value type. If the toolchain does not support it, the theoretical fit does not matter. Use a normal readonly struct or a plain class instead. The code that ships wins over the code that looks current.

Record classes still allocate

A record class is still a reference type. Creating one allocates. A with expression creates a copy. Equality can walk fields. If those fields are reference types or collections, the cost and meaning can be less obvious than the syntax suggests.

For many uses, that cost is fine. A settings object created in a menu is fine. A save migration descriptor is fine. A combat event emitted a few times per hit is probably fine. Editor tooling data is usually fine. Test expectations are fine.

Hot loops are different.

// Suspicious if this runs for thousands of agents every frame.
var next = currentSteering with
{
    DesiredVelocity = desiredVelocity,
    AvoidanceWeight = avoidanceWeight
};

The line is pleasant. Pleasant syntax does not make allocation free. If this runs inside Update for a crowd system, bullet pattern, pathing loop, perception pass, or planner inner loop, it may create garbage that the project did not need.

Do not guess here. Measure. Unity’s profiler, allocation call stacks, and a small benchmark usually answer the question faster than an argument about style. If the record sits on a cold path, keep the clarity. If it sits on a hot path, a normal struct, NativeArray, pooled object, or hand-written value type may be the better trade.

Record structs can avoid the reference allocation, but they do not make copying free. Large structs get expensive to pass around. Mutable structs are easy to misuse. A record struct with many fields, nested structs, or reference members can move the problem instead of solving it.

A useful rule: record classes are for clarity on cold or moderate paths. Record structs are for small values when the supported language version and copy cost make sense. Neither one is a default performance tool.

Good Unity use cases

Records fit best where data crosses a system boundary and should not own behavior.

Commands are a clean example:

public sealed record SpawnEnemyCommand(
    EnemyId Enemy,
    Vector3 Position,
    Quaternion Rotation,
    int Level);

A command describes something that should happen. It can be queued, logged, tested, replayed, rejected, or converted into another request. It is not the enemy instance.

Events are similar:

public sealed record EnemySpawnedEvent(
    EntityId Entity,
    EnemyId Enemy,
    Vector3 Position);

An event describes something that already happened. Value equality helps in tests. Generated ToString helps logs. The type is easy to pass through an event bus or gameplay pipeline because it is just facts.

Snapshots are another good fit:

public sealed record WeaponSnapshot(
    WeaponId Weapon,
    int AmmoInClip,
    int ReserveAmmo,
    float Heat);

var overheated = snapshot with { Heat = 1.0f };

A snapshot is not the live weapon. It is a captured view of the weapon at a point in time. That makes it useful for tests, UI projection, save previews, combat logs, and debugging tools. Copying a snapshot with one field changed can make a rule test small without building a scene.

Validated runtime specs can also work well:

public sealed record AbilitySpec(
    AbilityId Id,
    int BaseDamage,
    float CooldownSeconds,
    DamageType DamageType);

The word validated matters. Let the inspector-facing data stay flexible enough for authoring. Validate and convert it once. Then give runtime code a stable value object that no longer has to ask whether a string id is empty or a referenced asset is missing.

Be careful with Unity values and equality

Records can contain Vector3, Quaternion, Color, and other Unity structs. The syntax is not the issue. The issue is whether generated equality matches the way the game thinks.

Floating-point equality is often too strict. Two positions can be practically identical while still failing exact equality. A generated record equality check uses the equality behavior of its fields. That is useful for some data and misleading for physics-ish results, aiming solutions, steering outputs, animation blends, and sampled positions.

public sealed record AimSolution(Vector3 Direction, float TimeToImpact);

That type is fine as a return value. It becomes dangerous if gameplay starts treating exact equality between two aim solutions as meaningful.

Use records to carry values. Write explicit comparison logic when tolerance matters.

public static bool Approximately(AimSolution a, AimSolution b)
{
    return Vector3.Angle(a.Direction, b.Direction) < 0.5f
        && Mathf.Abs(a.TimeToImpact - b.TimeToImpact) < 0.05f;
}

Unity object references need the same caution. A record that contains a GameObject, Transform, or ScriptableObject mixes value equality with engine identity. Sometimes that is acceptable for a narrow request object. Often it is a smell. Passing ids, asset keys, or definition handles across a boundary usually keeps the record cleaner.

Records are better than repeated tuples at API boundaries

Tuples are useful inside a method:

(Vector3 position, float radius) query = (transform.position, 8f);

That local tuple is harmless. It groups two values for a small piece of code and then disappears.

The same tuple shape becomes harder to defend when it crosses a boundary:

public sealed record AwarenessQuery(Vector3 Position, float Radius);

A named record carries intent. It can be searched. It can be documented. It can grow carefully. Logs show a real type name instead of an anonymous pair. Tests can compare expected values without unpacking every field.

The rule is boring and useful:

• use tuples for throwaway grouping inside one small scope
• use records for named data that crosses method, system, queue, or test boundaries
• use normal classes or structs when behavior, lifecycle, serialization, or performance dominates

That avoids both over-typing and under-typing. Not every pair deserves a new type. Not every repeated tuple should stay anonymous after it becomes part of the design.

A boundary pattern that holds up

The safest Unity pattern is to split authoring data, runtime value data, and live state.

[Serializable]
public sealed class AbilityAuthoringData
{
    public string id;
    public int baseDamage;
    public float cooldownSeconds;
    public DamageType damageType;
}

public sealed record AbilitySpec(
    AbilityId Id,
    int BaseDamage,
    float CooldownSeconds,
    DamageType DamageType);

public sealed class AbilityRuntime
{
    private readonly AbilitySpec spec;
    private float cooldownRemaining;

    public AbilityRuntime(AbilitySpec spec)
    {
        this.spec = spec;
    }

    public bool CanCast => cooldownRemaining <= 0f;
}

The authoring class exists for Unity and designers. It can expose fields because the inspector wants fields. The record exists after validation. It gives runtime systems a compact, comparable value. The runtime class owns mutation, behavior, cooldowns, and lifecycle.

Trying to make one type serve all three roles usually creates the bug farm. If the type is inspector-friendly, it may be too mutable and too Unity-shaped for clean runtime value semantics. If it is record-shaped, it may be awkward or unsupported in Unity serialization. If it owns gameplay behavior, generated value equality probably lies about what the object means.

The boundary looks slightly more verbose at first. It usually removes weirdness later. Serialization bugs stay near authoring data. Runtime code gets clean values. Live objects keep identity. Tests get smaller because they can construct records without scene setup.

When records are not worth it

Avoid records when the generated behavior does not match the model.

Do not use records for most MonoBehaviour types. Do not use them for most ScriptableObject assets. Avoid them for serialized inspector models unless that path has been tested and documented. Avoid them for large mutable state objects. Avoid them for entities where identity matters more than field equality. Avoid them in hot loops until profiling says the allocations or copies are harmless.

Also avoid records when a plain class says the truth better:

public sealed class Health
{
    public int Current { get; private set; }
    public int Max { get; }

    public Health(int max)
    {
        Max = max;
        Current = max;
    }

    public void Damage(int amount)
    {
        Current = Math.Max(0, Current - amount);
    }
}

Health has invariants and behavior. It protects its state. It changes over time. Turning that into a record would make the code look modern while making the model less honest.

Good Unity code is allowed to be boring. A boring serializable class, a boring mutable runtime object, and a boring record used at the right boundary are all better than a clever type that fights its job.

Decision checklist

Before adding a record to a Unity project, ask:

1. Is the type mostly data?
2. Does value equality match the meaning of the type?
3. Will it stay out of Unity serialized fields?
4. Is allocation or copy cost acceptable for the path where it is created?
5. Does it avoid live Unity object references where ids or definitions would be clearer?
6. Does the whole team and build pipeline support the required C# language version?

If most answers are yes, a record is probably reasonable.

If the serialization, identity, language-version, or performance answers are shaky, use a normal class, struct, or serializable data class. That is not old-fashioned. That is matching the type to the job.

Practical takeaway

Use records in Unity for value-shaped runtime data: commands, events, snapshots, validated specs, editor-tool requests, save-pipeline steps, and test expectations. Keep them away from Unity serialization by default. Treat record structs as small value-type tools only when the Unity version and build pipeline support the syntax.

The clean pattern is a boundary. Boring serializable Unity data on one side. Compact runtime records after validation. Normal mutable classes for live gameplay objects. That gives a Unity project the useful part of modern C# without asking the engine serializer or object model to pretend it is something else.

References

• Unity Manual: C# compiler and language version reference — record support caveats, Unity language version, and serialization warning.
• Microsoft Learn: Records in C# — generated members, value equality, record classes, and record structs.
• Microsoft Learn: The history of C# — C# 10 feature list including record structs.
• Microsoft Learn: Tuple types — useful contrast between anonymous grouped values and named record types.

That is partly because mature frameworks have a lot of surface area: scopes, decorators, open generics, factories, validation, source generators, keyed services, child containers, disposal rules, Unity scene integration, and enough extension methods to make autocomplete tired. Useful tools, yes. Magic, no.

At the core, a DI container is an object-graph builder. It stores instructions that say “when someone asks for this type, build that type.” Then, when asked for an object, it walks the constructor parameters, builds the dependencies first, and finally calls the constructor.

That is the part worth understanding.

This article builds a small DI framework from scratch in C#. Not a production framework. Not a replacement for Microsoft.Extensions.DependencyInjection, Autofac, VContainer, Reflex, or whatever your project already uses. A teaching container. Small enough to read in one sitting, functional enough to explain what actually happens inside the box.

The ordinary problem

A lot of C# code starts like this:

public sealed class Player
{
    private readonly InventoryService inventory = new InventoryService();

    public void Pickup(Item item)
    {
        inventory.Add(item);
    }
}

That looks harmless because it is harmless when the project is tiny. The player needs inventory behavior, so it creates an inventory service.

Then the inventory service grows:

public sealed class InventoryService
{
    private readonly SaveService save = new SaveService();
    private readonly AudioService audio = new AudioService();

    public void Add(Item item)
    {
        // Add the item.
        save.MarkDirty();
        audio.Play("pickup");
    }
}

Now Player is not only coupled to InventoryService. It is indirectly coupled to SaveService and AudioService, because constructing inventory constructs those too. If AudioService later needs configuration, the dependency chain keeps spreading.

Testing also gets annoying. A simple player test now creates real save and audio services unless the code is rewritten. That is how a five-line unit test accidentally starts touching disk, playing sounds, loading assets, or depending on Unity scene state. Congratulations, the test now has side quests.

The first fix is constructor injection:

public sealed class Player
{
    private readonly IInventoryService inventory;

    public Player(IInventoryService inventory)
    {
        this.inventory = inventory;
    }

    public void Pickup(Item item)
    {
        inventory.Add(item);
    }
}

Now Player says what it needs. It does not know how inventory is built. It does not know whether the inventory implementation saves to disk, memory, cloud storage, or a fake test double.

That is dependency injection. A class receives its dependencies from the outside instead of constructing or locating them itself.

But this creates the next question:

var save = new SaveService();
var audio = new AudioService();
var inventory = new InventoryService(save, audio);
var player = new Player(inventory);

Something still needs to create SaveService, create AudioService, create InventoryService, create Player, and connect the graph in the right order.

For a small program, writing those new calls manually is fine. Do not over-engineer breakfast. But when the graph grows, teams often want one place to register construction rules and one resolver that can build the graph on demand.

That is the problem our tiny DI container will solve.

Stage 1: service registration

Start with the smallest useful registration API:

container.Register<IInventoryService, InventoryService>();

Conceptually, the container stores this mapping:

IInventoryService -> InventoryService

When someone asks for IInventoryService, the container should construct InventoryService.

Interfaces are common because they give the caller a narrow contract. Player should not care whether inventory is stored in memory, a save file, or a server-backed profile. It only needs IInventoryService.

But interfaces should not be required for everything. Sometimes a concrete class is already the right contract:

container.Register<GameManager, GameManager>();

That looks silly enough that we can support a shorter version later:

container.Register<GameManager>();

Internally, we need a dictionary keyed by the requested type.

public sealed class Container
{
    private readonly Dictionary<Type, ServiceDescriptor> services = new();
}

public sealed class ServiceDescriptor
{
    public ServiceDescriptor(Type serviceType, Type implementationType)
    {
        ServiceType = serviceType;
        ImplementationType = implementationType;
    }

    public Type ServiceType { get; }
    public Type ImplementationType { get; }
}

A ServiceDescriptor is just the container’s note to itself. It says which type callers ask for and which concrete type should be built.

Now add registration:

public sealed class Container
{
    private readonly Dictionary<Type, ServiceDescriptor> services = new();

    public void Register<TService, TImplementation>()
        where TImplementation : TService
    {
        services[typeof(TService)] = new ServiceDescriptor(
            typeof(TService),
            typeof(TImplementation));
    }

    public void Register<TService>()
    {
        services[typeof(TService)] = new ServiceDescriptor(
            typeof(TService),
            typeof(TService));
    }
}

That is the first piece of a DI framework. Very glamorous. A dictionary.

The where TImplementation : TService constraint catches obvious mistakes at compile time. This should compile:

container.Register<IInventoryService, InventoryService>();

This should not:

container.Register<IInventoryService, AudioService>();

The generic constraint does not solve every runtime problem, but it prevents one silly category of registration bug.

Stage 2: service resolution

Registration is only half the job. The container also needs to resolve a service:

var inventory = container.Resolve<IInventoryService>();

The first version can be naive. Look up the requested type, get the implementation type, and call its constructor.

public TService Resolve<TService>()
{
    return (TService)Resolve(typeof(TService));
}

private object Resolve(Type serviceType)
{
    if (!services.TryGetValue(serviceType, out var descriptor))
        throw new InvalidOperationException($"No registration for {serviceType.Name}");

    return Activator.CreateInstance(descriptor.ImplementationType)!;
}

Activator.CreateInstance is part of the standard library. It creates an instance of a type at runtime. For now, this only works for classes with a public parameterless constructor.

public interface IInventoryService
{
    void Add(Item item);
}

public sealed class InventoryService : IInventoryService
{
    public void Add(Item item)
    {
        // Store item.
    }
}

This works:

var container = new Container();
container.Register<IInventoryService, InventoryService>();

var inventory = container.Resolve<IInventoryService>();

The container looked up IInventoryService, found InventoryService, and created one.

Tiny, but real.

Stage 3: constructors with dependencies

The naive resolver breaks as soon as InventoryService needs something else:

public sealed class InventoryService : IInventoryService
{
    private readonly ISaveService save;

    public InventoryService(ISaveService save)
    {
        this.save = save;
    }
}

Activator.CreateInstance(type) only calls a parameterless constructor. There is no parameterless constructor now. The container needs to inspect the constructor, inspect its parameters, resolve those parameters, then call the constructor with the resolved objects.

This is the heart of automatic constructor injection.

C# reflection gives us metadata about types at runtime. A Type can tell us which constructors it has. A ConstructorInfo can tell us which parameters it expects. A ParameterInfo can tell us the type of each parameter.

Here is the next resolver:

private object Resolve(Type serviceType)
{
    if (!services.TryGetValue(serviceType, out var descriptor))
        throw new InvalidOperationException($"No registration for {serviceType.Name}");

    var implementationType = descriptor.ImplementationType;
    var constructor = SelectConstructor(implementationType);
    var parameters = constructor.GetParameters();

    var arguments = parameters
        .Select(parameter => Resolve(parameter.ParameterType))
        .ToArray();

    return constructor.Invoke(arguments);
}

private static ConstructorInfo SelectConstructor(Type implementationType)
{
    var constructors = implementationType.GetConstructors();

    if (constructors.Length != 1)
    {
        throw new InvalidOperationException(
            $"Type {implementationType.Name} must have exactly one public constructor.");
    }

    return constructors[0];
}

Now this can work:

public sealed class PlayerService
{
    public PlayerService(
        IInventoryService inventory,
        IAudioService audio)
    {
    }
}

When resolving PlayerService, the container walks this tree:

PlayerService
├── IInventoryService
│   └── InventoryService
└── IAudioService
    └── AudioService

That tree is the object graph. Each node is an object the container needs to build. Constructor parameters are edges to other nodes.

The resolver is recursive because dependencies can have dependencies. If InventoryService needs ISaveService, resolving PlayerService becomes:

PlayerService
├── IInventoryService
│   └── InventoryService
│       └── ISaveService
│           └── SaveService
└── IAudioService
    └── AudioService

The code is not doing anything mystical. It is walking constructor metadata and recursively calling Resolve for each parameter.

This is also where error handling matters. If InventoryService asks for ISaveService and ISaveService has not been registered, the container should say that clearly. A vague reflection exception is not enough.

Stage 4: resolving concrete types

The current container requires every type to be registered. That is simple, but it makes this annoying:

container.Register<GameManager>();
container.Register<PlayerService>();
container.Register<IInventoryService, InventoryService>();
container.Register<IAudioService, AudioService>();
container.Register<ISaveService, SaveService>();

var game = container.Resolve<GameManager>();

Some containers allow unregistered concrete types to be constructed automatically. If you ask for a concrete class and there is no registration, the container treats the class as its own implementation.

That means GameManager and PlayerService may not need explicit registrations, while interfaces still do.

private ServiceDescriptor GetDescriptor(Type serviceType)
{
    if (services.TryGetValue(serviceType, out var descriptor))
        return descriptor;

    if (!serviceType.IsAbstract && !serviceType.IsInterface)
    {
        return new ServiceDescriptor(serviceType, serviceType);
    }

    throw new InvalidOperationException($"No registration for {serviceType.Name}");
}

Then Resolve calls GetDescriptor instead of directly reading the dictionary.

private object Resolve(Type serviceType)
{
    var descriptor = GetDescriptor(serviceType);
    var implementationType = descriptor.ImplementationType;
    var constructor = SelectConstructor(implementationType);
    var parameters = constructor.GetParameters();

    var arguments = parameters
        .Select(parameter => Resolve(parameter.ParameterType))
        .ToArray();

    return constructor.Invoke(arguments);
}

This is a design choice. Auto-constructing concretes is convenient, especially for pure application services. Requiring explicit registration is stricter and can make the graph easier to audit. Production containers vary here.

For a learning container, allowing concrete self-binding keeps examples smaller while still forcing interfaces to be registered.

Stage 5: lifetimes

So far, every resolve creates a new instance. That is called a transient lifetime.

Resolve<IInventoryService>() -> new InventoryService
Resolve<IInventoryService>() -> another new InventoryService
Resolve<IInventoryService>() -> another new InventoryService

Sometimes that is exactly right. A command handler, small calculation service, temporary presenter, or short-lived object can be transient.

Other services should be shared. A save service, audio mixer, configuration object, telemetry client, or random source may need one instance reused across the graph. That is a singleton lifetime.

Add a lifetime enum:

public enum ServiceLifetime
{
    Transient,
    Singleton
}

Extend the descriptor:

public sealed class ServiceDescriptor
{
    public ServiceDescriptor(
        Type serviceType,
        Type implementationType,
        ServiceLifetime lifetime)
    {
        ServiceType = serviceType;
        ImplementationType = implementationType;
        Lifetime = lifetime;
    }

    public Type ServiceType { get; }
    public Type ImplementationType { get; }
    public ServiceLifetime Lifetime { get; }
    public object? SingletonInstance { get; set; }
}

Add registration helpers:

public void RegisterTransient<TService, TImplementation>()
    where TImplementation : TService
{
    services[typeof(TService)] = new ServiceDescriptor(
        typeof(TService),
        typeof(TImplementation),
        ServiceLifetime.Transient);
}

public void RegisterSingleton<TService, TImplementation>()
    where TImplementation : TService
{
    services[typeof(TService)] = new ServiceDescriptor(
        typeof(TService),
        typeof(TImplementation),
        ServiceLifetime.Singleton);
}

public void RegisterTransient<TService>()
{
    services[typeof(TService)] = new ServiceDescriptor(
        typeof(TService),
        typeof(TService),
        ServiceLifetime.Transient);
}

public void RegisterSingleton<TService>()
{
    services[typeof(TService)] = new ServiceDescriptor(
        typeof(TService),
        typeof(TService),
        ServiceLifetime.Singleton);
}

Now update resolution:

private object Resolve(Type serviceType)
{
    var descriptor = GetDescriptor(serviceType);

    if (descriptor.Lifetime == ServiceLifetime.Singleton &&
        descriptor.SingletonInstance != null)
    {
        return descriptor.SingletonInstance;
    }

    var instance = CreateInstance(descriptor.ImplementationType);

    if (descriptor.Lifetime == ServiceLifetime.Singleton)
    {
        descriptor.SingletonInstance = instance;
    }

    return instance;
}

Move constructor work into CreateInstance:

private object CreateInstance(Type implementationType)
{
    var constructor = SelectConstructor(implementationType);
    var parameters = constructor.GetParameters();

    var arguments = parameters
        .Select(parameter => Resolve(parameter.ParameterType))
        .ToArray();

    return constructor.Invoke(arguments);
}

The singleton cache lives on the descriptor. First resolve creates the instance. Later resolves return the cached object.

Scoped lifetimes are the next common feature in mature containers. A scoped service is reused inside one scope, such as one web request, one Unity scene, or one game match, but not globally forever. This article will not implement scopes because the simple container is already doing its teaching job. Just remember that scoped lifetime sits between transient and singleton.

Stage 6: registering existing instances

Sometimes the container should not construct the object. The object already exists.

In Unity, this matters because scene objects and MonoBehaviour components are usually created by Unity. Outside Unity, this is useful for configuration values, logging sinks, or objects created by platform code.

Add instance registration:

public void RegisterInstance<TService>(TService instance)
    where TService : notnull
{
    services[typeof(TService)] = new ServiceDescriptor(
        typeof(TService),
        instance.GetType(),
        ServiceLifetime.Singleton)
    {
        SingletonInstance = instance
    };
}

Now a prebuilt object can become part of the graph:

var settings = new GameSettings
{
    SaveSlot = "profile-1",
    MasterVolume = 0.8f
};

container.RegisterInstance(settings);

The container resolves GameSettings like any other singleton, but it does not own construction.

This is a tiny feature, but it connects the clean C# world to the messy real world where objects sometimes come from files, engines, scenes, command-line arguments, or platform callbacks.

Stage 7: recursive dependency graphs

With constructor injection, singleton caching, and concrete self-binding, the container can build a real graph.

GameManager
└── PlayerService
    ├── InventoryService
    │   └── SaveService
    └── AudioService

The code might look like this:

public sealed class GameManager
{
    private readonly PlayerService player;

    public GameManager(PlayerService player)
    {
        this.player = player;
    }
}

public sealed class PlayerService
{
    public PlayerService(
        IInventoryService inventory,
        IAudioService audio)
    {
    }
}

public sealed class InventoryService : IInventoryService
{
    public InventoryService(ISaveService save)
    {
    }
}