Skip to content

Game.CitizenUIUtils

Assembly: Assembly-CSharp.dll
Namespace: Game.UI.InGame

Type: public static class CitizenUIUtils

Base: System.Object

Summary:
A collection of helper functions used by the in-game UI to derive display-friendly information about citizens and households from ECS data. The methods query an EntityManager for components and buffers (Household, Citizen, Worker, HealthProblem, CurrentTransport, etc.), translate raw values into UI keys/enums (wealth, age, occupation, residence, workplace, state, conditions, happiness) and perform small aggregations (average household wealth, list of conditions). These helpers are intended for read-only UI usage; they rely on TryGetComponent/TryGetBuffer patterns and return safe defaults when components are missing.

Fields

  • None
    This static utility class defines no public or persistent private fields. All methods are stateless and operate on the passed-in EntityManager and data.

Properties

  • None
    There are no public properties on this static utility class.

Constructors

  • None (static class)
    CitizenUIUtils is declared static and has no instance constructor. All functionality is exposed through static methods.

Methods

  • public static HouseholdWealthKey GetHouseholdWealth(EntityManager entityManager, Entity householdEntity, CitizenHappinessParameterData happinessParameters)
    Returns a HouseholdWealthKey for the given household entity. It attempts to read a Household component and a Resources buffer to compute total household wealth via EconomyUtils.GetHouseholdTotalWealth, then compares the total to thresholds in happinessParameters.m_WealthyMoneyAmount (x,y,z,w) to return Wretched, Poor, Modest, Comfortable or Wealthy. If the household entity does not exist, the method returns Modest.

  • public static HouseholdWealthKey GetAverageHouseholdWealth(EntityManager entityManager, NativeList<Entity> households, CitizenHappinessParameterData happinessParameters)
    Computes the average total wealth across the provided household entities (summing per-household wealth via EconomyUtils.GetHouseholdTotalWealth). The average is computed safely (avoids divide-by-zero). The resulting average is compared to the same happinessParameters thresholds to return a HouseholdWealthKey.

  • public static CitizenJobLevelKey GetJobLevel(EntityManager entityManager, Entity entity)
    If the entity has a Worker component, returns the CitizenJobLevelKey corresponding to the worker's m_Level. If not present, returns CitizenJobLevelKey.Unknown.

  • public static CitizenAgeKey GetAge(EntityManager entityManager, Entity entity)
    Reads the Citizen component and returns a CitizenAgeKey derived from Citizen.GetAge(). If the Citizen component is missing, defaults to CitizenAgeKey.Adult.

  • public static CitizenOccupationKey GetOccupation(EntityManager entityManager, Entity entity)
    Determines the occupation key for a citizen entity by checking: whether the household is a TouristHousehold (returns Tourist), Criminal/Robber flags, presence of Worker, Student, or otherwise using age to determine Unemployed/None/Retired. Returns Unknown if it cannot be determined.

  • public static CitizenEducationKey GetEducation(Citizen citizen)
    Maps the citizen's education integer level (citizen.GetEducationLevel()) into a CitizenEducationKey: Uneducated, PoorlyEducated, Educated, WellEducated, HighlyEducated.

  • public static Entity GetResidenceEntity(EntityManager entityManager, Entity citizenEntity)
    Resolves the actual residence Entity for a citizen via the citizen's HouseholdMember → household entity. Checks in order: TouristHousehold.m_Hotel, PropertyRenter.m_Property, HomelessHousehold.m_TempHome. Returns Entity.Null if no residence is resolved.

  • public static CitizenResidenceKey GetResidenceType(EntityManager entityManager, Entity entity)
    Returns a CitizenResidenceKey (Home, Shelter, Hotel) based on the citizen's Citizen and HouseholdMember data and whether the household is homeless or marked as tourist. Defaults: Home if not tourist and not homeless, Shelter if homeless, Hotel if tourist.

  • public static Entity GetWorkplaceEntity(EntityManager entityManager, Entity citizenEntity)
    If the citizen has a Worker component, returns the worker's workplace. If the workplace is a PropertyRenter wrapper, returns the underlying Property (component2.m_Property). Returns Entity.Null if no Worker component.

  • public static Entity GetCompanyEntity(EntityManager entityManager, Entity citizenEntity)
    If the citizen has a Worker component, returns component.m_Workplace (even if it's a company). Returns Entity.Null if not a worker.

  • public static CitizenWorkplaceKey GetWorkplaceType(EntityManager entityManager, Entity entity)
    Determines whether the citizen's workplace is a Building or a Company. If the worker's workplace entity has a CompanyData component, returns Company; otherwise Building.

  • public static Entity GetSchoolEntity(EntityManager entityManager, Entity citizenEntity, out int level)
    If the citizen is a Student component, sets out parameter level to component.m_Level and returns the component.m_School entity. Otherwise sets level to 0 and returns Entity.Null.

  • public static CitizenStateKey GetStateKey(EntityManager entityManager, Entity entity)
    High-level mapping of a citizen's current state to a CitizenStateKey for UI display. Priority and checks include:

  • Dead via CitizenUtils.IsDead → CitizenStateKey.Dead
  • Involved in accident if current transport is a Creature and has InvolvedInAccident → InvolvedInAccident
  • If a travel purpose exists (via TryGetTravelPurpose), maps purpose (Shopping, Leisure, GoingHome, GoingToWork, Working, Sleeping, Exporting, MovingAway, Studying, etc.) into the appropriate CitizenStateKey, taking into account flags such as Tourist, Commuter and household moved-in/moved-away flags, and checks like PathEndReached for safety vs safe states.

  • Defaults to CitizenStateKey.Idling.

  • private static bool TryGetTravelPurpose(EntityManager entityManager, Entity entity, out Purpose purpose)
    Helper that tries to determine the current travel Purpose. First checks CurrentTransport -> Divert (only returns Safety, Shopping or SendMail from Divert), otherwise checks a TravelPurpose component on the citizen entity. Returns true and sets purpose if found; otherwise sets Purpose.None and returns false.

  • private static bool PathEndReached(EntityManager entityManager, Entity citizen)
    Helper that, given a citizen with CurrentTransport, checks if the transport has a HumanCurrentLane and queries CreatureUtils.PathEndReached to determine whether the path end was reached. Used to decide between "GettingToSafety" and "Safe".

  • public static NativeList<CitizenCondition> GetCitizenConditions(EntityManager entityManager, Entity entity, Citizen citizen, HouseholdMember householdMember, NativeList<CitizenCondition> conditions)
    Collects and returns a sorted list of CitizenCondition entries describing notable conditions: sick/injured/in distress (HealthProblem flags), Homeless (household is homeless and not a commuter/tourist/comms household), Evacuated (currently in an EmergencyShelter building), Weak (health <= 25), Unwell (well-being <= 25). Adds conditions into the supplied NativeList and sorts it before returning. Note: the method mutates and returns the supplied NativeList.

  • public static CitizenHappiness GetCitizenHappiness(Citizen citizen)
    Returns a CitizenHappiness instance for a Citizen by converting the citizen's happiness value into a CitizenHappinessKey using CitizenUtils.GetHappinessKey.

  • public static CitizenHappiness GetCitizenHappiness(int happiness)
    Returns CitizenHappiness for an integer happiness value by mapping via CitizenUtils.GetHappinessKey.

Notes and considerations: - All methods use EntityManager read operations (TryGetComponent/TryGetBuffer/GetComponentData). Callers should ensure the EntityManager passed is valid and consistent with the world state; these are intended for UI/display and are not safe to call concurrently with structural changes without appropriate synchronization. - Many methods return sensible defaults (Entity.Null, Unknown keys, Modest wealth) when components are missing. - Several methods rely on external utility classes (EconomyUtils, BuildingUtils, CreatureUtils, CitizenUtils) and game-specific component types (Household, HouseholdMember, Worker, TravelPurpose, CurrentTransport, HealthProblem, TouristHousehold, PropertyRenter, HomelessHousehold, CompanyData, etc.). Ensure those types are available in the mod environment.

Usage Example

// Example: get a citizen's display data for a UI panel
EntityManager em = World.DefaultGameObjectInjectionWorld.EntityManager;
Entity citizenEntity = /* obtained elsewhere */;
Citizen citizen = em.GetComponentData<Citizen>(citizenEntity);
HouseholdMember hm = em.GetComponentData<HouseholdMember>(citizenEntity);

// Get happiness
CitizenHappiness happiness = CitizenUIUtils.GetCitizenHappiness(citizen);

// Get residence and workplace
Entity residence = CitizenUIUtils.GetResidenceEntity(em, citizenEntity);
Entity workplace = CitizenUIUtils.GetWorkplaceEntity(em, citizenEntity);

// Get state for an icon or tooltip
CitizenStateKey stateKey = CitizenUIUtils.GetStateKey(em, citizenEntity);

// Get conditions
NativeList<CitizenCondition> conditions = new NativeList<CitizenCondition>(Allocator.Temp);
conditions = CitizenUIUtils.GetCitizenConditions(em, citizenEntity, citizen, hm, conditions);
// ... use conditions, then dispose
conditions.Dispose();

If you want, I can also produce per-method XML-style documentation comments suitable for adding back into the source file.