Game.Simulation.AreaSpawnSystem

Assembly: Game
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
AreaSpawnSystem is a simulation system responsible for populating Area entities with spawned objects (buildings, placeable objects, nets, sub-areas, etc.). It schedules a Burst-compiled chunk job (AreaSpawnJob) that iterates Area archetype chunks, evaluates storage/extractor capacities, selects and places spawnable prefabs and placeholder objects, creates CreationDefinition / ObjectDefinition entities for spawned objects, and can spawn nested sub-areas and sub-nets. The system uses TerrainSystem and WaterSystem data to adjust object elevation, consults city configuration (e.g. left-hand traffic), and issues commands through an EndFrameBarrier command buffer. It runs at a reduced update frequency (once every 64 frames).

---

Fields

• private TerrainSystem m_TerrainSystem
  Reference to the TerrainSystem used to obtain TerrainHeightData for position/elevation adjustments during spawn placement.

• private WaterSystem m_WaterSystem
  Reference to the WaterSystem used to obtain WaterSurfaceData for object placement relative to water surfaces.

• private CityConfigurationSystem m_CityConfigurationSystem
  Used to read city configuration such as left-hand traffic for net orientation.

• private EndFrameBarrier m_EndFrameBarrier
  Barrier used to create a command buffer (parallel writer) and register job producer handles so entity creation/modification occurs safely after the job completes.

• private EntityQuery m_AreaQuery
  Query selecting Area entities with required components (Area, Geometry, SubObject buffer) and excluding Temp/Destroyed/Deleted; required for system updates.

• private EntityArchetype m_DefinitionArchetype
  Archetype used for creating definition entities (CreationDefinition + ObjectDefinition + Updated + Deleted) for spawned objects.

• private TypeHandle __TypeHandle
  Internal struct aggregating Entity/component/buffer handles and component lookups used to build the AreaSpawnJob (populated via __AssignHandles).

Properties

• public bool debugFastSpawn { get; set; }
  When enabled, used by the job to fast-populate or fast-calc storage/extractor values for debugging/testing spawn behavior (m_DebugFastSpawn is passed into the job).

Constructors

• public AreaSpawnSystem()
  Default constructor (preserved). Initialization is performed in OnCreate; the constructor itself does not perform heavy initialization.

Methods

• public override int GetUpdateInterval(SystemUpdatePhase phase)
  Returns the update interval for the system. AreaSpawnSystem returns 64 (i.e., it runs every 64 frames).

• [Preserve] protected override void OnCreate()
  Initializes internal subsystem references (TerrainSystem, WaterSystem, CityConfigurationSystem), obtains the EndFrameBarrier, creates the Area entity query (Area + Geometry + SubObject buffer, excludes Temp/Destroyed/Deleted), creates the definition archetype used for spawned objects, and calls RequireForUpdate(m_AreaQuery) so the system only updates when matching Area entities exist.

• [Preserve] protected override void OnUpdate()
  Constructs and schedules the Burst-compiled AreaSpawnJob in parallel across Area query chunks. The job is configured with type handles, component lookups, buffer lookups, terrain/water data, random seed, and the EndFrameBarrier command buffer (AsParallelWriter). After scheduling it registers the job with TerrainSystem and WaterSystem as readers and adds the job handle to EndFrameBarrier so produced entity changes are applied safely. The system updates base.Dependency with the scheduled job handle.

• protected override void OnCreateForCompiler()
  Compiler helper that assigns queries and component handles (calls __AssignQueries and __TypeHandle.__AssignHandles).

• [MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignQueries(ref SystemState state)
  Internal method used by compiler-generated code to construct/assign any queries required for compilation-time correctness. (No runtime query changes; present for codegen support.)

• Nested: AreaSpawnJob (private struct, [BurstCompile], implements IJobChunk)

• Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
  The main chunk-processing method. For each Area in the chunk it:
  • Computes the available object area based on storage and extractor components (and can fast-fill values when debugFastSpawn is set).
  • Collects existing sub-objects (non-secondary) and their radii/positions to avoid overlap.
  • If needed, chooses spawnable prefabs (respects placeholder requirements and spawn probabilities).
  • Attempts to find a valid random object location within the area (AreaUtils.TryGetRandomObjectLocation) and adjusts the transform with ObjectUtils.AdjustPosition (using TerrainHeightData and WaterSurfaceData).
  • Creates CreationDefinition/ObjectDefinition entities through the command buffer via SpawnObject and, when spawning buildings, removes conflicting objects and marks affected areas updated.
  • Handles creation of nested sub-areas and sub-nets by creating permanent CreationDefinition entities and adding NetCourse / nodes as components (CreateSubNet / Spawn methods).
  • Cleans up native collections (NativeList / NativeParallelHashSet) used during processing.
• TryGetObjectPrefab / TryGetObjectPrefab (overloads)
  Helpers that pick a prefab from a prefabSubObjects buffer according to flags (skipping edge placement), handles placeholder elements and requirements, evaluates probabilities, and fills placeholderRequirements from owner/company data when needed.
• FillRequirements(ref NativeParallelHashSet placeholderRequirements, Owner owner)
  Populates placeholder requirements using owner/company/renter data to ensure placeholder-specific spawn constraints (brands/prefabs) are respected.
• Spawn(...) overloads
  Two overloads used to spawn sub-areas (creating new Area CreationDefinitions with node buffers) and sub-nets (collects averaged node positions and creates net CreationDefinition with NetCourse).
• CreateSubNet(...)
  Creates a net CreationDefinition + NetCourse setup with world-transformed Bezier curves and start/end CoursePos configuration. Attaches Upgraded component if upgrades are present.
• SpawnObject(...)
  Creates a CreationDefinition and ObjectDefinition entity for a spawned object and, if the prefab contains sub-areas or sub-nets, calls the spawn helpers to create nested definitions.

Notes about job behavior: - The job uses a RandomSeed derived random per chunk index so spawns are deterministic per seed. - Many component & buffer lookups are used (PrefabRef, ObjectGeometryData, SpawnableObjectData, BuildingData, PlaceableObjectData, AreaGeometryData, StorageAreaData, ExtractorAreaData, NetGeometryData, etc.) to make placement decisions. - It disposes any temporary Native collections it creates and uses the EndFrameBarrier's parallel command buffer to safely create entities from a job.

Usage Example

// Example: toggle debug fast spawn from another system or mod initializer
[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    var areaSpawn = World.GetOrCreateSystemManaged<Game.Simulation.AreaSpawnSystem>();
    areaSpawn.debugFastSpawn = true; // enable fast spawn behavior for debugging
}

(For runtime behavior, AreaSpawnSystem is scheduled and controlled by the game's simulation loop. Modders typically interact by changing prefabs, placeholder elements, or by toggling debugFastSpawn.)