Game.RandomLocalizationSystem

Assembly: Game
Namespace: Game.Serialization

Type: class

Base: GameSystemBase

Summary:
RandomLocalizationSystem is an ECS system responsible for ensuring that entities carrying RandomLocalizationIndex buffers have valid random localization indices assigned. It iterates over entities that have RandomLocalizationIndex and PrefabRef components, looks up the localization counts for the referenced prefab (or its zone prefab via SpawnableBuildingData), and fills or clears the RandomLocalizationIndex buffer by using a deterministic RandomSeed per entity. The work is performed in a Burst-compiled IJobChunk (EnsureLocalizationJob) and scheduled as a chunk job for performance.

---

Fields

• private EntityQuery m_Query
  Holds the query used to select entities that need localization indices. The query looks for entities with RandomLocalizationIndex and PrefabRef (both read-only for the query requirement). RequireForUpdate(m_Query) is called in OnCreate to ensure the system only runs when matching entities exist.

• private TypeHandle __TypeHandle
  Holds the cached type handles and buffer/component lookups used by job scheduling. The nested TypeHandle struct contains the EntityTypeHandle, ComponentTypeHandle, BufferTypeHandle, BufferLookup, and ComponentLookup. These are assigned via __AssignHandles in OnCreateForCompiler to avoid repeated lookups each frame.

• (Nested) private struct EnsureLocalizationJob
  A Burst-compiled IJobChunk that does the real work per chunk:

• Reads entities and PrefabRef components.
• Accesses the RandomLocalizationIndex dynamic buffer for each entity.
• For each entity, it resolves the effective prefab (prefab or its m_ZonePrefab if a SpawnableBuildingData is present).
• Attempts to get the LocalizationCount buffer for that prefab. If present, it uses a Random instance derived from the system's RandomSeed and the entity index to ensure deterministic randomization and calls RandomLocalizationIndex.EnsureValidRandomIndices to populate the buffer. If no LocalizationCount buffer is available, it clears the RandomLocalizationIndex buffer.
• Uses BufferLookup and ComponentLookup for read-only access to other data.

• Implemented as Execute(in ArchetypeChunk, ...) and explicit interface implementation for IJobChunk.

• (Nested) private struct TypeHandle
  Encapsulates all Component/Buffer/Entity type handles used by the system and provides __AssignHandles(ref SystemState) to initialize them from a SystemState. This minimizes overhead when scheduling jobs.

Properties

• None (this system does not expose public properties).

Constructors

• public RandomLocalizationSystem()
  Parameterless constructor (marked with [Preserve]). Initializes the system instance; actual initialization of queries and type handles happens in OnCreate and OnCreateForCompiler.

Methods

• protected override void OnCreate()
  Initializes the entity query m_Query to find entities with RandomLocalizationIndex and PrefabRef. Calls RequireForUpdate(m_Query) so the system runs only when entities matching the query exist.

• protected override void OnUpdate()
  Creates an instance of EnsureLocalizationJob by filling its fields using the cached __TypeHandle via InternalCompilerInterface helpers and a freshly generated RandomSeed (RandomSeed.Next()). Schedules the job with JobChunkExtensions.Schedule(jobData, m_Query, base.Dependency) and assigns the returned handle to base.Dependency so it integrates with the job dependency chain.

• protected override void OnCreateForCompiler()
  Called by generated code paths / compiler plumbing. It calls __AssignQueries(ref base.CheckedStateRef) (a small helper that builds/disposes an EntityQueryBuilder) and __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to initialize the cached type handles for job scheduling.

• private void __AssignQueries(ref SystemState state)
  Helper used during compiler-time initialization; currently creates and disposes an EntityQueryBuilder (placeholder pattern used by generated systems). Marked MethodImplOptions.AggressiveInlining in the TypeHandle for its assignment method.

• (Nested EnsureLocalizationJob) public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
  The chunk-execution implementation that processes each entity in the chunk, resolving prefabs and localization counts, constructing deterministic Random instances (m_RandomSeed.GetRandom(1 + entity.Index)), and invoking RandomLocalizationIndex.EnsureValidRandomIndices or clearing the buffer when appropriate.

Notes: - The job is Burst-compiled ([BurstCompile]) and implements IJobChunk for efficient chunk-based parallel processing. - It uses BufferLookup and ComponentLookup for read-only access to other entity data. - Deterministic randomization uses a RandomSeed per-schedule and the entity.Index to vary per-entity results reproducibly.

Usage Example

// The system is self-contained and scheduled by the runtime. Example: showing how it schedules the job in OnUpdate.
[Preserve]
protected override void OnUpdate()
{
    var jobData = new EnsureLocalizationJob
    {
        m_EntityType = InternalCompilerInterface.GetEntityTypeHandle(ref __TypeHandle.__Unity_Entities_Entity_TypeHandle, ref base.CheckedStateRef),
        m_PrefabRefType = InternalCompilerInterface.GetComponentTypeHandle(ref __TypeHandle.__Game_Prefabs_PrefabRef_RO_ComponentTypeHandle, ref base.CheckedStateRef),
        m_RandomLocalizationType = InternalCompilerInterface.GetBufferTypeHandle(ref __TypeHandle.__Game_Common_RandomLocalizationIndex_RW_BufferTypeHandle, ref base.CheckedStateRef),
        m_LocalizationCounts = InternalCompilerInterface.GetBufferLookup(ref __TypeHandle.__Game_Prefabs_LocalizationCount_RO_BufferLookup, ref base.CheckedStateRef),
        m_SpawnableBuildingDatas = InternalCompilerInterface.GetComponentLookup(ref __TypeHandle.__Game_Prefabs_SpawnableBuildingData_RO_ComponentLookup, ref base.CheckedStateRef),
        m_RandomSeed = RandomSeed.Next()
    };

    base.Dependency = JobChunkExtensions.Schedule(jobData, m_Query, base.Dependency);
}

Additional notes for modders: - The system relies on the existence of LocalizationCount buffers attached to prefab entities. Ensure your prefab definitions include LocalizationCount buffers if you expect random localization assignment. - RandomLocalizationIndex.EnsureValidRandomIndices is the central utility that picks/validates indices; inspect that method if you need custom behavior. - Because the job is Burst-compiled and uses deterministic RandomSeed behavior, results are reproducible across runs given the same seed and entity indices.