Game.HouseholdFindPropertySystem

Assembly: Game
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
HouseholdFindPropertySystem is a simulation system responsible for matching households (including homeless households) with available residential properties. It prepares a cache of free residential properties and their generic quality (via a PreparePropertyJob), then processes households (via a FindPropertyJob) to either start pathfinding to candidate properties or enqueue rent actions. The system integrates with many city subsystems (pollution, telecom, tax, pathfinding, property processing, etc.) and throttles work across frames using configured limits and an update interval. It also exposes a debug flag to disable homeless handling and several debug distributions for profiling evaluation costs. The system runs every 16 simulation frames.

Fields

public bool debugDisableHomeless
Toggle to disable homeless handling (useful for debugging/testing).
private const int UPDATE_INTERVAL = 16
Update interval in simulation frames (returned by GetUpdateInterval).
public static readonly int kMaxProcessEntitiesPerUpdate = 128
Maximum number of household entities processed per update (global throttling constant).
public static readonly int kFindPropertyCoolDown = 5000
Cooldown (in simulation frames) between property seek attempts for a household.
private DebugWatchDistribution m_DefaultDistribution
Debug/profiling distribution used by the system.
private DebugWatchDistribution m_EvaluateDistributionLow
Debug/profiling distribution for low-evaluation cases.
private DebugWatchDistribution m_EvaluateDistributionMedium
Debug/profiling distribution for medium-evaluation cases.
private DebugWatchDistribution m_EvaluateDistributionHigh
Debug/profiling distribution for high-evaluation cases.
private DebugWatchDistribution m_EvaluateDistributionLowrent
Debug/profiling distribution for low-rent evaluation cases.
private EntityQuery m_HouseholdQuery
Query for (non-homeless) households looking for properties.
private EntityQuery m_HomelessHouseholdQuery
Query for homeless households.
private EntityQuery m_FreePropertyQuery
Query for free residential property entities to prepare cache from.
private EntityQuery m_EconomyParameterQuery
Query used to require EconomyParameterData for update.
private EntityQuery m_DemandParameterQuery
Query used to require DemandParameterData for update.
private EndFrameBarrier m_EndFrameBarrier
Barrier used to create a command buffer that executes at end of frame.
private PathfindSetupSystem m_PathfindSetupSystem
Reference to PathfindSetupSystem used to enqueue pathfinding setup requests.
private TaxSystem m_TaxSystem
Reference to TaxSystem (provides tax rates for scoring).
private TriggerSystem m_TriggerSystem
Reference to TriggerSystem (action buffers etc.).
private GroundPollutionSystem m_GroundPollutionSystem
Reference to ground pollution map provider.
private AirPollutionSystem m_AirPollutionSystem
Reference to air pollution map provider.
private NoisePollutionSystem m_NoisePollutionSystem
Reference to noise pollution map provider.
private TelecomCoverageSystem m_TelecomCoverageSystem
Reference to telecom coverage map provider.
private CitySystem m_CitySystem
Reference to the city system (city entity and modifiers).
private CityStatisticsSystem m_CityStatisticsSystem
Reference to city statistics system (writer dependency used).
private SimulationSystem m_SimulationSystem
Reference to the simulation (frame index provider).
private PropertyProcessingSystem m_PropertyProcessingSystem
System providing the RentAction queue writer.
private CountResidentialPropertySystem m_CountResidentialPropertySystem
Provides aggregated residential property data (free counts etc.).
private EntityQuery m_HealthcareParameterQuery
Query for healthcare parameters (required for scoring).
private EntityQuery m_ParkParameterQuery
Query for park parameters (required for scoring).
private EntityQuery m_EducationParameterQuery
Query for education parameters.
private EntityQuery m_TelecomParameterQuery
Query for telecom parameters.
private EntityQuery m_GarbageParameterQuery
Query for garbage parameters.
private EntityQuery m_PoliceParameterQuery
Query for police configuration parameters.
private EntityQuery m_CitizenHappinessParameterQuery
Query for citizen happiness parameters.
private TypeHandle __TypeHandle
Internal container of ComponentLookup/BufferLookup/EntityTypeHandle used by jobs.

Nested Types

public struct CachedPropertyInformation
Holds precomputed property information used by FindPropertyJob:
GenericApartmentQuality quality — generic property quality metrics used for initial scoring.
int free — number of free slots (available units / homeless capacity) in the property.
public struct GenericApartmentQuality
Generic aggregate metrics for property quality:
float apartmentSize
float2 educationBonus
float welfareBonus
float score
int level
private struct PreparePropertyJob : IJobChunk (BurstCompile)
Iterates free residential property entities (m_FreePropertyQuery), computes:
number of free units via CalculateFree
a GenericApartmentQuality using PropertyUtils.GetGenericApartmentQuality
stores a CachedPropertyInformation entry into a NativeParallelHashMap (as parallel writer) The job reads many component lookups and maps (pollution, telecom, service coverages, parameters) and only adds properties with free > 0.
private struct FindPropertyJob : IJob (BurstCompile)
Processes two entity lists:
homeless households list (m_HomelessHouseholdEntities)
moved-in / other households list (m_MovedInHouseholdEntities) Responsibilities:
For each household (throttled by kMaxProcessEntitiesPerUpdate) decide whether to start pathfinding to find a home or to process existing path results.
StartHomeFinding: prepares PathfindParameters and enqueues pathfinding setup using PathfindSetupSystem (via m_PathfindQueue) and marks PathInformation on the household.
ProcessPathInformations: handles completed pathfinding results (PathInformations buffer) and evaluates candidate properties using the cached property info and PropertyUtils.GetPropertyScore, enqueues rent actions into m_RentActionQueue when a suitable property is found, and decrements cached free counts.
Handles special cases: homeless shelter handling, property on market checks, inadequate income, moving away (HouseholdMoveAway), and disabling the PropertySeeker component when a household is settled.
private struct TypeHandle
Generated container that stores all EntityTypeHandle / ComponentLookup / BufferLookup objects used by jobs and assigns them from SystemState in OnCreateForCompiler.

Properties

None (the system exposes no public properties beyond inherited members).

Constructors

public HouseholdFindPropertySystem()
Default constructor (Preserve attribute on OnCreate/OnDestroy/OnUpdate methods ensures system persists across IL2CPP stripping).

Methods

public override int GetUpdateInterval(SystemUpdatePhase phase)
Returns 16 — indicates system runs every 16 simulation frames.
[Preserve] protected override void OnCreate()
Initializes subsystem references (EndFrameBarrier, PathfindSetupSystem, pollution/telecom/city/tax/trigger systems, etc.), defines entity queries for households and free properties, and sets up debug distributions. Also registers required parameter queries to ensure system only runs with required singletons present.
[Preserve] protected override void OnDestroy()
Disposes debug distribution resources.
[Preserve] protected override void OnUpdate()
Main update function:
Allocates a temporary NativeParallelHashMap to hold cached property info sized by free property entity count.
Retrieves pollution maps and telecom data (as read-only arrays) and collects job dependencies.
Builds PreparePropertyJob, schedules it as a parallel JobChunk over m_FreePropertyQuery.
Builds FindPropertyJob, gathers homeless and household entity lists, and schedules it (dependent on PreparePropertyJob).
Adds produced dependencies to EndFrameBarrier and other systems that need to be aware of readers/writers.
Disposes of the temporary cachedPropertyInfo map (scheduled for disposal with the dependency).
protected override void OnCreateForCompiler()
Internal helper used by generated code to assign queries and type handles in compiled builds.
private void __AssignQueries(ref SystemState state)
(Compiler-generated helper) — empty in this class; placeholder for query assignment in generated builds.
[MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignHandles(ref SystemState state) (in TypeHandle)
Assigns all ComponentLookup / BufferLookup / EntityTypeHandle fields from the provided SystemState.
Additional job-level methods (inside PreparePropertyJob and FindPropertyJob): CalculateFree, Execute (job run methods), StartHomeFinding, GetFirstWorkplaceOrSchool, GetCurrentLocation, ProcessFindHome, ProcessPathInformations — these encapsulate the property counting, scoring, pathfinding setup and rent action enqueueing logic.

Usage Example

// Get the system and toggle homeless handling (for mod/debug tools)
var system = World.DefaultGameObjectInjectionWorld.GetOrCreateSystemManaged<Game.Simulation.HouseholdFindPropertySystem>();
system.debugDisableHomeless = true;

// Alternatively, you can inspect or log when the system runs by using debug distributions
// (m_DefaultDistribution, etc. are internal debug helpers exposed in the class)

Notes and important behaviors: - The system tightly interops with many other systems (pathfinding, pollution, telecom, tax, property processing). Mods altering those subsystems or the property scoring utilities (PropertyUtils / BuildingUtils / CitizenUtils) will affect household behavior. - PreparePropertyJob computes a light-weight GenericApartmentQuality for each free property, enabling FindPropertyJob to avoid re-evaluating expensive property metrics repeatedly. - FindPropertyJob uses pathfinding to evaluate candidate properties in proximity (it enqueues pathfinding via PathfindSetupSystem). It also supports households using owned vehicles and can include car/taxi methods in path search depending on owned vehicles and origin/destination context. - The system uses NativeParallelHashMap for cross-job communication (caching free slots), and it carefully decrements cached free counts when rent actions are enqueued, to avoid multiple households choosing the same unit. - Throttling is in place to avoid overloading simulation each frame (kMaxProcessEntitiesPerUpdate and GetUpdateInterval).