Skip to content

Game.UI.InGame.ResidentsSection

Assembly:
Assembly-CSharp (Unity game assembly)

Namespace:
Game.UI.InGame

Type:
class

Base:
InfoSectionBase

Summary:
ResidentsSection is an in-game UI info section used by Cities: Skylines 2 to display resident-related information for the selected entity (building, household, district or area). It gathers counts (residents, pets, households, max households), calculates average household wealth, accumulates age and education distributions, and resolves residence information (home / hotel / shelter). The class uses Unity.Entities ECS queries and Burst-compiled jobs (CountHouseholdsJob and CountDistrictHouseholdsJob) to collect data efficiently on the worker threads and then processes results on the main thread for UI presentation. It also exposes serialization via OnWriteProperties for the UI system.

Fields

  • private EntityQuery m_DistrictBuildingQuery
    Holds an EntityQuery used to iterate residential buildings in a district. Created in OnCreate and used by the CountDistrictHouseholdsJob schedule.

  • private EntityQuery m_HappinessParameterQuery
    Query used to obtain citizen happiness parameter data (used when computing wealth/average household properties).

  • private NativeArray<int> m_Results
    NativeArray of length 5 used as a small result buffer from the jobs. Indices map to Result enum: Visible (0), ResidentCount (1), PetCount (2), HouseholdCount (3), MaxHouseholds (4).

  • private NativeValue<Entity> m_ResidenceResult
    Single NativeValue used to return a residence Entity from the job (when computing residence for a household or renter).

  • private NativeList<Entity> m_HouseholdsResult
    NativeList populated by the jobs with household Entities found for the selection. Used later to gather age/education/wealth.

  • private TypeHandle __TypeHandle
    Internal structure that stores various Entity/Component handles and ComponentLookups for scheduling ECS jobs. Populated on create-for-compiler.

  • protected override string group => "ResidentsSection"
    Identifier used by the UI system to group this info section.

  • private bool isHousehold { get; set; }
    Property flag indicating whether the selected entity is a Household entity.

  • private int householdCount { get; set; }
    Number of households found for the current selection.

  • private int maxHouseholds { get; set; }
    Maximum household capacity as reported by building prefab/property data.

  • private HouseholdWealthKey wealthKey { get; set; }
    Computed average household wealth key (used for UI display).

  • private int residentCount { get; set; }
    Computed number of living residents for the selection.

  • private int petCount { get; set; }
    Computed number of pets associated with the households.

  • private Entity residenceEntity { get; set; }
    Resolved residence Entity (e.g., building or park used as shelter) for display.

  • private CitizenResidenceKey residenceKey { get; set; }
    Enum key indicating the residence type (Home, Hotel, Shelter, etc).

  • private EducationData educationData { get; set; }
    Aggregated education distribution data for the residents.

  • private AgeData ageData { get; set; }
    Aggregated age distribution data for the residents.

  • Nested types (brief):

  • Result enum — indexes used inside m_Results.
  • CountHouseholdsJob — IJob that counts households/residents/pets for a single selected entity.
  • CountDistrictHouseholdsJob — IJobChunk that counts households across a district area.
  • TypeHandle — holds entity/component handles and provides assignment helper.

Properties

  • public bool isHousehold { get; private set }
    Indicates whether the selected entity is itself a household. (private setter in original code via auto-property)

  • public int householdCount { get; private set }
    Number of households counted.

  • public int maxHouseholds { get; private set }
    Capacity for households (from prefab property data).

  • public HouseholdWealthKey wealthKey { get; private set }
    Average household wealth key computed from households list.

  • public int residentCount { get; private set }
    Number of residents (excludes corpses picked up by hearses).

  • public int petCount { get; private set }
    Number of pets across households.

  • public Entity residenceEntity { get; private set }
    Resolved residence entity for display (or Entity.Null).

  • public CitizenResidenceKey residenceKey { get; private set }
    Type of residence (Home, Hotel, Shelter, etc).

  • public EducationData educationData { get; private set }
    Aggregated education levels.

  • public AgeData ageData { get; private set }
    Aggregated age distribution.

Note: The original source uses auto-properties with private setters (generated backing fields). These properties are updated in OnProcess after jobs complete.

Constructors

  • public ResidentsSection()
    Default constructor. Marked with [Preserve] attribute in methods to avoid stripping in AOT builds. Initialization of Native containers is done in OnCreate rather than constructor.

Methods

  • protected override void OnCreate()
    Initializes entity queries and allocates persistent native containers:
  • m_DistrictBuildingQuery for iterating residential buildings in a district.
  • m_HappinessParameterQuery to fetch happiness parameters.

  • Allocates m_HouseholdsResult (NativeList), m_ResidenceResult (NativeValue) and m_Results (NativeArray). This method is called when the UI system creates the section.

  • protected override void OnDestroy()
    Disposes Native containers (m_HouseholdsResult, m_ResidenceResult, m_Results) and calls base.OnDestroy. Always free Native memory here.

  • protected override void Reset()
    Resets internal state between uses: clears native lists, zeroes counts and result buffer, clears age/education accumulators and resets residence result.

  • protected override void OnUpdate()
    Main update entry for the UI section. Decides whether the selected entity is a district/area (schedules CountDistrictHouseholdsJob with m_DistrictBuildingQuery) or a single building/household (schedules CountHouseholdsJob). Jobs are scheduled via ECS job helpers and completed immediately (Complete()) so results are available on the main thread. Sets base.visible based on m_Results[0] (Visible).

  • protected override void OnProcess()
    Runs after OnUpdate and when the section should compute derived metrics from job data:

  • Determines isHousehold from selection.
  • Reads counts from m_Results into the properties (householdCount, residentCount, petCount, maxHouseholds).
  • Computes wealthKey by calling CitizenUIUtils.GetAverageHouseholdWealth with m_HouseholdsResult and happiness params singleton.
  • Aggregates ageData and educationData either by iterating m_HouseholdsResult or using the selected household buffer directly.
  • Resolves residenceEntity and residenceKey based on m_ResidenceResult and component presence (TouristHousehold, HomelessHousehold).

  • Adds tooltip tags (HomelessShelter) when appropriate (e.g., parks or abandoned buildings used as shelter with renters).

  • private AgeData GetAgeData(DynamicBuffer<HouseholdCitizen> citizens)
    Given a buffer of HouseholdCitizen entries, iterates and counts children, teens, adults, elderly while skipping corpses (checks via CitizenUtils.IsCorpsePickedByHearse). Returns an AgeData struct populated with the counts.

  • private EducationData GetEducationData(DynamicBuffer<HouseholdCitizen> citizens)
    Given a buffer of HouseholdCitizen entries, iterates and counts education levels (0..4) while skipping corpses. Returns an EducationData struct.

  • public override void OnWriteProperties(IJsonWriter writer)
    Serializes the current UI section state (isHousehold, counts, wealthKey, residence, ageData, educationData, etc.) for UI/inspector display. Uses m_NameSystem to write the readable name of residenceEntity when present; otherwise writes null.

  • private static bool TryCountHouseholds(ref int residentCount, ref int petCount, ref int householdCount, ref int maxHouseholds, Entity entity, Entity prefab, ref ComponentLookup<Game.Buildings.Park> parkLookup, ref ComponentLookup<Abandoned> abandonedLookup, ref ComponentLookup<BuildingPropertyData> propertyDataLookup, ref ComponentLookup<HealthProblem> healthProblemLookup, ref ComponentLookup<TravelPurpose> travelPurposeLookup, ref ComponentLookup<Household> householdLookup, ref BufferLookup<Renter> renterLookup, ref BufferLookup<HouseholdCitizen> householdCitizenLookup, ref BufferLookup<HouseholdAnimal> householdAnimalLookup, NativeList<Entity> householdsResult)
    Core static helper used by both job variants. Determines whether a building/prefab can host households (residential properties or park/abandoned with renters), accumulates maxHouseholds from prefab property data, iterates renter buffers to count households and residents (skipping corpses) and collects pets counts. Adds valid household Entities to householdsResult. Returns true if the entity contributes household data (so the UI section is visible).

  • private void __AssignQueries(ref SystemState state)
    Internal helper emitted by the authoring/compiler — in this file it constructs (and immediately disposes) an EntityQueryBuilder. Used during OnCreateForCompiler.

  • protected override void OnCreateForCompiler()
    Compiler-time creation helper: calls base and assigns component/entity handles via __AssignHandles on __TypeHandle. Called as part of generated setup.

  • Nested job structs:

  • CountHouseholdsJob : IJob — Burst compiled job that runs for a single selected entity and calls TryCountHouseholds. Writes results into m_Results, m_HouseholdsResult and optionally sets m_ResidenceResult.

  • CountDistrictHouseholdsJob : IJobChunk — Burst compiled job chunk that iterates building chunks in a district and accumulates aggregated counts across entities into m_Results and m_HouseholdsResult.

  • void IJobChunk.Execute(...)
    Explicit interface implementation forwarding to the struct's Execute for CountDistrictHouseholdsJob (generated by Burst/ECS codegen). Not normally invoked directly outside of scheduler.

Usage Example

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

    // ResidentsSection will allocate native containers and queries in OnCreate,
    // so overriding and calling base is important.
    // After OnCreate, the section will schedule CountHouseholdsJob or CountDistrictHouseholdsJob
    // during OnUpdate to populate resident/household data for UI display.
}

Additional notes for modders: - The class relies on Unity.Entities component lookups and buffers; care must be taken if you modify component names or buffer types. - Native containers (NativeArray, NativeList, NativeValue) are allocated with Allocator.Persistent and disposed in OnDestroy — if you extend this class ensure to free any added native memory. - Jobs are completed immediately (Complete()) to make results available synchronously to the UI; if you change scheduling to work asynchronously, you must manage dependencies and safety handles correctly. - The TryCountHouseholds helper skips corpse citizens (via CitizenUtils.IsCorpsePickedByHearse) and treats parks/abandoned buildings with Renter buffers as homeless shelter sources.