// Cluster behaviour — enemies grouping in gameplay

Wave Spawner ECS is the second assessment for GDEV50004 Advanced Mechanics Design at Staffordshire University (Level 5, Year 2). While the Tank Controller explored physics simulation with a traditional MonoBehaviour architecture, this project explored a completely different paradigm: Unity's Entity Component System (ECS) architecture via Unity.Entities 1.4.4 with Burst compilation.

The assignment was to build an enemy wave spawner. Rather than a simple array of prefab spawns, the solution builds a full data pipeline: wave configuration defined in human-readable .TomBen text files → parsed at authoring time → baked from managed C# into unmanaged NativeCollections → driven by an ISystem-based ECS runtime that manages wave progression, population caps, spawn delays, and enemy AI entirely in ECS — no MonoBehaviour in the hot path.

The project includes a real-time ECS debug panel (UI Toolkit) displaying live FPS, entity count, enemy count, wave progress, rule index, and next spawn delay. Enemy seek AI navigates toward the player via ECS transforms. Collision damage is processed through ECS physics events. Five .TomBen example files demonstrate edge cases in the parser: Simple, Mixed, Optional, Partial, and Duplicate.

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

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.

Stage 2 — Runtime (unmanaged): SpawnerDataSingleton is guarded — if a second instance is ever created, the system immediately throws a UnityException. A separate WaveProgress entity tracks the current wave index. The original WaveSpawnerSystem.cs — fully written — was commented out and superseded by this singleton-driven approach, with a comment from the author: "my mum said to make this script obsolete".

Key ECS systems built:

TomBen is a custom human-readable data format invented for this project to define enemy wave configurations as plain text files. It uses three structural tokens: _Tom (block open), _Ben (block close), and !? (field separator). Three definition types exist — type, cluster, and wave — and they can appear in any order in the file; the parser resolves references by ID.

Syntax reference:

Example — AMD_ECS_Mixed_E.TomBen:

Definitions are intentionally order-independent — the parser makes two passes, first registering all IDs, then resolving cross-references. This allows wave definitions to reference clusters that appear later in the file, mirroring how a level designer would think (waves first, then unit details).

The parser (TomBenParser.cs) tokenises on _Tom / _Ben / !? boundaries. It populates WaveSpawnerDataAuthoring arrays which are then baked into ECS component data via WaveSpawnerCreateSingletonSystem on OnStartRunning.

Five example files provided:

// Runtime — 30% wave spawned // Runtime — 70% wave spawned // Runtime — 90% wave spawned

The ECS Debug Panel (built with UI Toolkit) displays real-time ECS state directly in the game view. It reads from the SpawnerDataSingleton and WaveProgress entities each frame to surface the full wave runtime state without any MonoBehaviour involvement in the data path.

The WaveSpawnerDataAuthoringEditor is a custom Unity editor (Editor/ folder) that provides an in-editor wave preview and a TomBen asset drag-in button. Designers can drag a .TomBen TextAsset into the authoring component and click Load to immediately populate all wave, cluster, and unit arrays — no play mode required.

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.

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.

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.

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.

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.