Skip to content

Game.Simulation.GraduationSystem

Assembly:
Game (assembly containing simulation/game systems)
Namespace:
Game.Simulation

Type:
class (derived system)

Base:
GameSystemBase

Summary:
GraduationSystem is an ECS simulation system responsible for processing students every simulation update: deciding graduations, dropouts, and failures. It schedules a parallel IJobChunk (GraduationJob) over entities with Game.Citizens.Student + Citizen components, consults building/school data and city modifiers, enqueues trigger actions (CitizenGraduated, CitizenDroppedOutSchool, CitizenFailedSchool), and uses an EndFrameBarrier EntityCommandBuffer to apply entity/component changes (e.g., remove Student component). The system also exposes static helper methods used to compute graduation and dropout probabilities.

Fields

  • public int debugFastGraduationLevel
    Controls forced/fast graduation debugging behavior. If non-zero, the job will only consider students at that specific education level (or behave as configured) which makes debugging graduation easier. Set to 0 for normal behavior.

  • public const int kUpdatesPerDay = 1
    Constant used to determine update frequency relative to day ticks. (System uses SimulationUtils.GetUpdateFrame with a 1-per-day cadence.)

  • public const int kCheckSlowdown = 2
    Constant present in the class (likely used to spread out checks across frames); included for completeness.

  • private SimulationSystem m_SimulationSystem
    Reference to the SimulationSystem (provides frameIndex and other global simulation state). Assigned in OnCreate.

  • private EndFrameBarrier m_EndFrameBarrier
    Barrier used to obtain an EntityCommandBuffer for applying structural changes at end of frame/job. Used by the GraduationJob to remove Student components and add StudentsRemoved to buildings.

  • private CitySystem m_CitySystem
    Reference to the CitySystem to obtain the current city entity. Assigned in OnCreate.

  • private TriggerSystem m_TriggerSystem
    Reference to the TriggerSystem used to create trigger action buffers and enqueue citizen-related triggers (graduated, dropped out, failed).

  • private EntityQuery m_StudentQuery
    Query used to gather all student entities (Game.Citizens.Student (ReadOnly) + Citizen (ReadWrite) + UpdateFrame). Required for scheduling the GraduationJob.

  • private TypeHandle __TypeHandle
    Generated container storing type handles (EntityTypeHandle, ComponentTypeHandles, BufferLookups, etc.) used to construct the job data. Populated by __AssignHandles in compiler flow.

  • private EntityQuery __query_1855827631_0
    Generated EntityQuery used to fetch singleton EconomyParameterData in OnUpdate.

  • private EntityQuery __query_1855827631_1
    Generated EntityQuery used to fetch singleton TimeData in OnUpdate.

Properties

  • None (no public properties exposed by this system)
    This system primarily exposes methods and fields; the behavior is driven via OnCreate/OnUpdate and the debug field.

Constructors

  • public GraduationSystem()
    Default constructor (Preserve attribute applied elsewhere on lifecycle methods). No custom initialization beyond what the ECS system base provides; key setup occurs in OnCreate.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns 16384 (system update interval used by the game). This controls how often the system is considered for updating in specific phases.

  • public static float GetDropoutProbability(Citizen citizen, int level, float commute, float fee, int wealth, uint simulationFrame, ref EconomyParameterData economyParameters, SchoolData schoolData, DynamicBuffer<CityModifier> modifiers, float efficiency, TimeData timeData)
    High-level helper that computes a citizen's probability to drop out given full runtime context (citizen struct, school data, city modifiers, efficiency, time & economy data). Internally computes age, studyWillingness and failed counts and defers to the lower-level overload.

  • public static float GetDropoutProbability(int level, float commute, float fee, int wealth, float age, float studyWillingness, int failedEducationCount, float graduationProbability, ref EconomyParameterData economyParameters)
    Pure math implementation that computes dropout probability given numeric parameters (age, wages, benefits, commute cost, fee, failed count, graduation probability). Uses game-economy parameters (wages, unemployment benefit) to determine whether staying in school is economically sensible; returns a probability in [0,1].

  • public static float GetGraduationProbability(int level, int wellbeing, SchoolData schoolData, DynamicBuffer<CityModifier> modifiers, float studyWillingness, float efficiency)
    Convenience overload that fetches city modifiers for college/university graduation and calls the detailed overload.

  • public static float GetGraduationProbability(int level, int wellbeing, float graduationModifier, float2 collegeModifier, float2 uniModifier, float studyWillingness, float efficiency)
    Core graduation probability function. Uses wellbeing, study willingness, school modifiers, building efficiency and level-specific formulas to compute the chance a student graduates at a given level. Handles levels:

  • level 1: primary/elementary style smoothstep formula,
  • level 2: intermediate formula using log,
  • level 3: college using log + collegeModifier,

  • level 4: university scaled by uniModifier. If efficiency is near zero, returns 0. Final result is adjusted by graduationModifier.

  • protected override void OnCreate()
    Initializes references to SimulationSystem, EndFrameBarrier, TriggerSystem and CitySystem. Builds the student EntityQuery and registers the required singletons (EconomyParameterData, TimeData). Calls RequireForUpdate on the student query and on the required singletons so the system runs only when the relevant data exists.

  • protected override void OnUpdate()
    Prepares and schedules the parallel GraduationJob:

  • Computes updateFrame via SimulationUtils.GetUpdateFrame(...).
  • Fills GraduationJob struct with type handles, component lookups, buffers, singleton data (EconomyParameterData, TimeData), random seed and city reference.
  • Schedules the job using JobChunkExtensions.ScheduleParallel over m_StudentQuery.

  • Adds the job handle to m_EndFrameBarrier (producer) and registers the trigger action buffer writer with TriggerSystem. The scheduled job iterates chunked students and applies graduation/dropout logic in parallel.

  • private void __AssignQueries(ref SystemState state)
    Generated helper that creates the internal queries used to obtain EconomyParameterData and TimeData singletons. Called during system construction for compiler/runtime correctness.

  • protected override void OnCreateForCompiler()
    Compiler-generated hook that calls __AssignQueries and assigns type handles (via __TypeHandle.__AssignHandles). Used in build/runtime codegen path.

  • (Inner type) public struct GraduationJob : IJobChunk
    The job that does the per-student processing. Key behavior:

  • Skips chunks that are not scheduled for this update frame (using UpdateFrame shared component) unless debug fast graduation is enabled.
  • Iterates students in the chunk, uses a Random seeded per chunk.
  • For each student, obtains the associated school prefab and SchoolData, applies installed building upgrades to the school's data, gets citizen wellbeing, study willingness, building efficiency, and computes graduation probability.
  • Depending on debug settings and random draws it either:
    • graduates the student (updates Citizen education level, removes Student component, enqueues a CitizenGraduated trigger, and marks the school via StudentsRemoved), or
    • increments failed education count and possibly computes dropoutChance (including fee and economy data) — may cause dropout trigger & removing Student, or
    • if failedEducationCount exceeds threshold the student is forced to leave and a failed-school trigger is enqueued.
  • Uses EntityCommandBuffer.ParallelWriter to apply structural changes safely from the job.

  • Removes TravelPurpose if the citizen was currently going to school/studying.

  • (Inner GraduationJob method) private void LeaveSchool(int chunkIndex, Entity entity, Entity school)
    Helper used inside the job to add StudentsRemoved to the school, remove Game.Citizens.Student from the citizen, and remove TravelPurpose if appropriate.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();

    // Typical setup performed by GraduationSystem
    m_SimulationSystem = base.World.GetOrCreateSystemManaged<SimulationSystem>();
    m_EndFrameBarrier = base.World.GetOrCreateSystemManaged<EndFrameBarrier>();
    m_TriggerSystem = base.World.GetOrCreateSystemManaged<TriggerSystem>();
    m_CitySystem = base.World.GetOrCreateSystemManaged<CitySystem>();

    // Query for students (Student + Citizen + UpdateFrame) and require economy/time singletons
    m_StudentQuery = GetEntityQuery(
        ComponentType.ReadOnly<Game.Citizens.Student>(),
        ComponentType.ReadWrite<Citizen>(),
        ComponentType.ReadOnly<UpdateFrame>()
    );
    RequireForUpdate(m_StudentQuery);
    RequireForUpdate<EconomyParameterData>();
    RequireForUpdate<TimeData>();
}

Notes / Modding tips: - The static GetGraduationProbability and GetDropoutProbability methods are useful when creating custom school prefabs or balancing mods — they encapsulate the game's formulas. - The system uses city modifiers (CityModifier buffer) and installed building upgrades: mods that change those buffers or SchoolData/PrefabRef will affect outcomes. - GraduationJob schedules in parallel and writes structural changes through EndFrameBarrier's command buffer; to reliably observe changes in the same frame, use the barrier/job handles properly. - For debugging, set debugFastGraduationLevel to force certain behaviors (fast progression or targeted testing).