Wave Spawner ECS

The core design challenge in ECS is that managed C# objects — class arrays, strings, reference types — cannot live inside ECS components. Everything must be blittable, unmanaged, and safe for Burst compilation. The project solves this with a two-stage authoring and runtime pipeline.

Stage 1 — Authoring (managed): WaveSpawnerDataAuthoring is a standard MonoBehaviour that holds managed arrays of C# wave, cluster, and unit definitions. These are populated either directly in the inspector or by loading a .TomBen file via the custom WaveSpawnerDataAuthoringEditor. At bake time, Unity's ECS baker converts this component into a lightweight wrapper.

// Unity editor — ECS authoring view at 50% wave

// WaveSpawnerCreateSingletonSystem.OnStartRunning
// Reads the baked SpawnerDataWrapper, converts all arrays to NativeHashMaps
var unitMap    = new NativeHashMap<int, UnitData>   (units.Length,    Allocator.Persistent);
var clusterMap = new NativeHashMap<int, ClusterData>(clusters.Length, Allocator.Persistent);
var waveMap    = new NativeHashMap<int, WaveData>   (waves.Length,    Allocator.Persistent);
var waveOrder  = new NativeArray<int>(orderedWaveIds, Allocator.Persistent);

// All packed into SpawnerDataSingleton on a single authoritative entity
EntityManager.SetComponentData(singleton, new SpawnerDataSingleton {
    Units    = unitMap,
    Clusters = clusterMap,
    Waves    = waveMap,
    WaveOrder = waveOrder
});

type    - <id> (<name>) _Tom health=><n>!?speed=><n>!?damage=><n>!? _Ben
cluster - <id> (<name>) _Tom <unitId>:<count>!? _Ben
wave    - <id> (<name>) _Tom C<clusterId>[<popCap>]!?T<typeId>[<delay>]!? _Ben

wave    - 1 (start)  _Tom C1<1>!?C1<5>!?C2<5>!? _Ben
type    - 1 (small)  _Tom health=>10!?speed=>5!?damage=>1!? _Ben
wave    - 2 (boss)   _Tom C2<1>!?C2<1>!?C2<1>!? _Ben
cluster - 2 (elite)  _Tom 1:1!?2:2!? _Ben
type    - 2 (big)    _Tom health=>20!?speed=>5!?damage=>1!? _Ben
cluster - 1 (simple) _Tom 1:3!? _Ben

• AMD_ECS_Simple_E.TomBen
• AMD_ECS_Mixed_E.TomBen
• AMD_ECS_Optional_E.TomBen
• AMD_ECS_Partial_E.TomBen
• AMD_ECS_Duplicate_E.TomBen

1. Issue 01

   ECS null-reference style errors don't work the same as OOP.

   Unmanaged structs have no null state — a missing component causes structural query failures, not NullReferenceExceptions. This required learning RequireForUpdate and TryGetSingleton patterns before any runtime system could safely access singleton data. Early iteration frequently crashed the editor rather than throwing a catchable exception.

2. Issue 02

   NativeCollection lifetime management.

   Every NativeHashMap and NativeList allocated with Allocator.Persistent in OnCreate must be manually disposed in OnDestroy. Forgetting a single disposal causes Unity to emit a memory leak warning on every recompile until the project is restarted — a persistent and confusing error that was traced back to the NativeArray waveOrder allocation.

3. Issue 03

   Managed-to-unmanaged conversion.

   C# class arrays cannot live in ECS components. Every field in the authoring data required explicit translation: string names to FixedString64Bytes, List<int> to NativeList<int>, Dictionary to NativeHashMap. The SpawnRuleData struct required three separate blittable fields to encode what was originally a polymorphic C# class hierarchy.

4. Issue 04

   The original WaveSpawnerSystem was fully written then abandoned.

   Once the singleton-driven architecture proved correct, the original system — which queried entities directly rather than reading from a centralised singleton — was commented out in its entirety. The comment left in source: "my mum said to make this script obsolete". The singleton pattern is now the sole runtime authority.

5. Issue 05

   TomBenParser CS8632 nullable annotation warnings.

   The TomBen parser used nullable reference types (string?) which required the C# 8 nullable context. Enabling it project-wide would cascade warnings across all existing Unity-generated files. Resolved by enabling the nullable context only on TomBenParser.cs via a #nullable enable pragma at the file level.