Skip to content

Game.Simulation.XPBuiltSystem

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
XPBuiltSystem is an ECS system used by the game to grant XP rewards when buildings or upgrades are built and to award a one‑time XP bonus when any electricity consumer in the city has fulfilled consumption (i.e., the electricity grid is effectively built). The system schedules two Burst-compiled jobs:

  • XPBuiltJob: runs over newly created PrefabRef entities (built objects) to enqueue XP gains for placeable objects and service upgrades, and to add a PlacedSignatureBuildingData component for signature buildings.
  • XPElectricityJob: inspects ElectricityConsumer components and, if any consumer has fulfilled consumption, enqueues a one-time XP reward for the electricity network and marks the city XP record so the bonus is only granted once.

The system uses an XPSystem-provided NativeQueue to enqueue XP gains, uses a ModificationEndBarrier to add components safely via a parallel EntityCommandBuffer, and only runs while the ToolSystem is in game mode.

Fields

  • private EntityQuery m_BuiltGroup
    Query matching entities that represent newly created prefabs to process for build XP. Constructed as entities with PrefabRef and Created and excluding Temp.

  • private EntityQuery m_ElectricityGroup
    Query matching entities that have ElectricityConsumer components (used to detect if the electricity grid has been satisfied).

  • private XPSystem m_XPSystem
    Reference to the game's XPSystem—used to obtain the NativeQueue where this system enqueues XP gains.

  • private ToolSystem m_ToolSystem
    Reference to the ToolSystem; used to check current action mode and only run XP awarding logic in game mode.

  • private CitySystem m_CitySystem
    Reference to the CitySystem; used to retrieve the city entity and its XP component for marking the electricity-grid XP reward as granted.

  • private ModificationEndBarrier m_ModificationEndBarrier
    Used to create an EntityCommandBuffer.ParallelWriter for safely adding components (e.g., PlacedSignatureBuildingData) from jobs.

  • private static readonly int kElectricityGridXPBonus = 25
    Constant XP amount granted once when the electricity network is detected as built (per city).

  • private TypeHandle __TypeHandle
    Internal container struct that holds EntityTypeHandle, ComponentTypeHandle and ComponentLookup handles used when scheduling jobs and accessing components.

  • Nested types (structs):

  • XPBuiltJob (BurstCompile) — IJobChunk implementation that iterates built prefabs and enqueues XPGain entries or adds PlacedSignatureBuildingData to prefabs via an ECB.
  • XPElectricityJob (BurstCompile) — IJob implementation that scans electricity consumers, enqueues electricity-grid XP, and updates the city's XP component.
  • TypeHandle — helper struct that assigns and stores component handles for job usage.

Properties

  • None (no public properties exposed by this system).

Constructors

  • public XPBuiltSystem()
    Default parameterless constructor. The system is initialized by the Unity/DOTS world and initializes dependencies in OnCreate.

Methods

  • protected override void OnCreate()
    Initializes required systems and entity queries:
  • Acquires references to XPSystem, CitySystem, ToolSystem and ModificationEndBarrier from the World.
  • Creates two EntityQuery instances:
    • m_BuiltGroup: PrefabRef (read-only) + Created + Exclude Temp.
    • m_ElectricityGroup: ElectricityConsumer (read-only) + Exclude Temp.

  • Calls RequireAnyForUpdate with the two queries so the system updates if either query has matching entities.

  • protected override void OnUpdate()
    Main update path:

  • Early-exits unless ToolSystem.actionMode.IsGame() (system only runs in game mode).
  • Obtains the NativeQueue and its dependency handle from m_XPSystem.GetQueue.
  • If m_BuiltGroup is not empty: schedules XPBuiltJob (IJobChunk) to process created prefabs. The job:
    • Reads PrefabRef components and inspects the referenced prefab entity for PlaceableObjectData, SignatureBuildingData, PlacedSignatureBuildingData and ServiceUpgradeData via ComponentLookup.
    • If a PlaceableObjectData has m_XPReward > 0, enqueues an XPGain with reason XPReason.ServiceBuilding.
    • If the prefab has SignatureBuildingData and lacks PlacedSignatureBuildingData, adds PlacedSignatureBuildingData to the prefab via the parallel command buffer.
    • If a ServiceUpgradeData has m_XPReward > 0, enqueues an XPGain with reason XPReason.ServiceUpgrade.
  • If the city's XP has not yet recorded the ElectricityGridBuilt reward and m_ElectricityGroup is not empty: schedules XPElectricityJob (IJob) to:
    • Read ElectricityConsumer components; if any consumer has m_FulfilledConsumption > 0, enqueue an XPGain of amount kElectricityGridXPBonus with reason XPReason.ElectricityNetwork and set the city's XP.m_XPRewardRecord flag ElectricityGridBuilt.

  • Adds the queue writer dependency back into the XPSystem with m_XPSystem.AddQueueWriter(base.Dependency).

  • protected override void OnCreateForCompiler()
    Compiler helper that assigns component handles and calls __AssignQueries; used by generated/compiled code paths. Calls __AssignQueries and __TypeHandle.__AssignHandles to initialize handles for job scheduling.

  • private void __AssignQueries(ref SystemState state)
    Internal method referenced by OnCreateForCompiler. Present for compiler-generated plumbing; the implementation in this class creates and disposes an EntityQueryBuilder (no custom runtime behavior beyond that in this version).

  • Nested job methods:

  • XPBuiltJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
    Iterates the chunk's PrefabRef array and, for each element:
    • Gets prefab Entity reference and checks for PlaceableObjectData and PlacedSignatureBuildingData.
    • Enqueues XPGain entries for placeable object XP and service upgrade XP where applicable.
    • Adds PlacedSignatureBuildingData to the prefab entity via the parallel ECB if it has SignatureBuildingData and not yet PlacedSignatureBuildingData.
  • XPElectricityJob.Execute()
    Iterates a NativeArray (DeallocateOnJobCompletion). If any consumer's m_FulfilledConsumption > 0:
    • Enqueues a single XPGain (kElectricityGridXPBonus) for the electricity network.
    • Marks the city XP component's m_XPRewardRecord with XPRewardFlags.ElectricityGridBuilt to prevent re-awarding.

Notes: - Both jobs are Burst-compiled for performance. - ComponentLookup and ComponentTypeHandle access is passed into jobs via the TypeHandle and InternalCompilerInterface to respect runtime safety checks. - The system uses a parallel EntityCommandBuffer (ModificationEndBarrier) to add components from within jobs. - XP awarding is performed by enqueuing XPGain objects into the XPSystem's NativeQueue; the actual application of XP is handled elsewhere by the XPSystem.

Usage Example

// This system is a managed GameSystemBase system and is created/updated by the DOTS world.
// Example snippet showing how the system schedules work in its OnUpdate (simplified):

[Preserve]
protected override void OnUpdate()
{
    if (m_ToolSystem.actionMode.IsGame())
    {
        // Get XP queue and dependency
        JobHandle deps;
        NativeQueue<XPGain> queue = m_XPSystem.GetQueue(out deps);

        // Schedule job to handle newly built prefabs
        if (!m_BuiltGroup.IsEmptyIgnoreFilter)
        {
            var job = new XPBuiltJob
            {
                m_EntityType = /* assigned via TypeHandle in actual system */,
                m_PrefabRefType = /* assigned via TypeHandle */,
                m_PlaceableObjectDatas = /* component lookup */,
                m_SignatureBuildingDatas = /* component lookup */,
                m_PlacedSignatureBuildingDatas = /* component lookup */,
                m_ServiceUpgradeDatas = /* component lookup */,
                m_XPQueue = queue,
                m_CommandBuffer = m_ModificationEndBarrier.CreateCommandBuffer().AsParallelWriter()
            };
            base.Dependency = JobChunkExtensions.Schedule(job, m_BuiltGroup, deps);
        }

        // Schedule electricity XP job if needed...
        m_XPSystem.AddQueueWriter(base.Dependency);
    }
}

(See the system source for exact handle initialization and full implementation details.)