Skip to content

Game.Serialization.DataMigration.ResidentPseudoRandomSystem

Assembly: Game
Namespace: Game.Serialization.DataMigration

Type: class

Base: GameSystemBase

Summary:
ResidentPseudoRandomSystem is a compiler-generated ECS system used during data migration when loading older save versions. If the loaded save version predates the resident pseudo-random fix (Version.residentPseudoRandomFix), the system finds entities with Resident and PseudoRandomSeed components and populates each resident's PseudoRandomSeed using the corresponding Citizen's pseudo-random generator (CitizenPseudoRandom.SpawnResident). The work is performed in a Burst-compiled IJobChunk (ResidentPseudoRandomJob) and scheduled in parallel.

Fields

  • private LoadGameSystem m_LoadGameSystem
    Holds a reference to the LoadGameSystem so the system can inspect the currently-loading save context and its version (m_LoadGameSystem.context.version) to determine whether migration is required.

  • private EntityQuery m_Query
    An EntityQuery that selects entities having a read-only Resident component and a read-write PseudoRandomSeed component. Used to drive the JobChunk scheduling.

  • private TypeHandle __TypeHandle
    Compiler-generated container for component type handles and lookups (Resident read-only, PseudoRandomSeed read-write, Citizen read-only). Populated by __AssignHandles and used to create the job's ComponentTypeHandle/ComponentLookup instances.

(Note: The type contains two nested structs: ResidentPseudoRandomJob (Burst-compiled IJobChunk implementing the migration logic) and the TypeHandle struct (assigns component handles).)

Properties

  • This class exposes no public properties.

Constructors

  • public ResidentPseudoRandomSystem()
    Default public constructor. Marked with [Preserve] in the original source to prevent stripping.

Methods

  • protected override OnCreate() : System.Void
    Initializes the system by retrieving the LoadGameSystem from the world and creating the EntityQuery (Resident read-only, PseudoRandomSeed read-write). This prepares the system to run migration during OnUpdate.

  • protected override OnUpdate() : System.Void
    Checks the load context version through m_LoadGameSystem.context.version. If the save version is older than Version.residentPseudoRandomFix and the query is not empty, constructs a ResidentPseudoRandomJob with component handles/lookups obtained from the compiler TypeHandle and schedules it in parallel (JobChunkExtensions.ScheduleParallel). The job fills PseudoRandomSeed components for residents based on their associated Citizen pseudo-random generator.

  • protected override OnCreateForCompiler() : System.Void
    Compiler helper that calls __AssignQueries and __AssignHandles to ensure the component handles and queries are assigned for the generated code path.

  • private void __AssignQueries(ref SystemState state) : System.Void
    Internal/compiled helper that currently creates and disposes an EntityQueryBuilder(Allocator.Temp). Exists to satisfy the compiler-generated scaffolding; effectively a placeholder to ensure queries are assigned where necessary.

  • private void __AssignHandles(ref SystemState state) (on nested TypeHandle)
    Assigns the ComponentTypeHandle (read-only), ComponentTypeHandle (read-write), and ComponentLookup (read-only) from the provided SystemState. Called from OnCreateForCompiler to prepare handles for job construction.

  • private struct ResidentPseudoRandomJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask) : System.Void
    JobChunk body that:

  • Retrieves Resident and PseudoRandomSeed native arrays from the chunk.
  • Iterates each resident in the chunk and attempts to lookup the corresponding Citizen component via m_CitizenData.TryGetComponent(resident.m_Citizen, out componentData).
  • If the Citizen is present, obtains a Random via componentData.GetPseudoRandom(CitizenPseudoRandom.SpawnResident) and writes a new PseudoRandomSeed constructed from that Random into the resident's PseudoRandomSeed component slot. This job is Burst-compiled and scheduled in parallel by the system.

Usage notes: - The job uses InternalCompilerInterface to obtain the job's component handles and lookups from the compiler-generated __TypeHandle fields and the system's CheckedStateRef. - The job explicitly implements IJobChunk.Execute and calls the internal Execute method.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // This mirrors what the game system does: cache LoadGameSystem and create the query
    m_LoadGameSystem = base.World.GetOrCreateSystemManaged<LoadGameSystem>();
    m_Query = GetEntityQuery(ComponentType.ReadOnly<Resident>(), ComponentType.ReadWrite<PseudoRandomSeed>());
}

// The system's OnUpdate will check the load version and schedule a Burst IJobChunk
// (ResidentPseudoRandomJob) that fills PseudoRandomSeed components for residents
// using their associated Citizen's pseudo-random generator.

Notes and tips for modders: - This system is specifically for migrating older save data; it only runs when loading saves with versions older than Version.residentPseudoRandomFix. - The job relies on the Citizen component exposing GetPseudoRandom(CitizenPseudoRandom) to produce deterministic seeds for residents. - Because the job uses Burst and ScheduleParallel, take care when modifying the job to maintain thread-safety and respect Burst limitations (no managed object access, etc.).