Skip to content

Game.UI.NameSystem

Assembly: Game
Namespace: Game.UI

Type: class NameSystem

Base: GameSystemBase, IDefaultSerializable, ISerializable

Summary:
NameSystem is the central system for resolving, binding and serializing entity names in the game UI. It: - Maintains a runtime dictionary of custom names assigned to entities (m_Names). - Produces Name values (a nested struct) that represent custom, localized or formatted names for entities and UI bindings. - Resolves localization IDs and title IDs for prefabs using PrefabSystem and PrefabUISystem. - Handles name-related cleanup when entities with CustomName are deleted (via an entity query and OnUpdate). - Uses an EndFrameBarrier to enqueue entity commands (add/remove CustomName, mark BatchesUpdated) so changes are applied at the right time in the frame. - Implements serialization (Serialize/Deserialize) to persist m_Names and SetDefaults to clear them on default load.

Nested types: - NameType (enum): Custom, Localized, Formatted — used to express how the Name should be rendered or serialized. - Name (struct): a small value type that can be created via Name.CustomName, Name.LocalizedName or Name.FormattedName. It can write itself to an IJsonWriter (Bind-style binding) and supports binary serialize/deserialize (IWriter/IReader).

Fields

  • private Unity.Entities.EntityQuery m_DeletedQuery
    Used to find entities that have a CustomName component and have become Deleted so their entries can be removed from the m_Names dictionary during OnUpdate.

  • private PrefabSystem m_PrefabSystem
    Cached reference to the PrefabSystem for prefab lookups, localization components, and obsolete ID fallback resolution.

  • private PrefabUISystem m_PrefabUISystem
    Cached reference to PrefabUISystem used to obtain title and description IDs for prefabs when a Localization component is not present.

  • private EndFrameBarrier m_EndFrameBarrier
    Used to create EntityCommandBuffer instances so component add/remove operations (e.g., Add/Remove CustomName, Add BatchesUpdated) are performed at the end of the frame.

  • private System.Collections.Generic.Dictionary<Unity.Entities.Entity, string> m_Names
    In-memory map from Entity -> custom name string. This is serialized/deserialized by the system and is the authoritative store for custom names while the game is running.

Properties

  • This class exposes no public properties.

Constructors

  • public NameSystem()
    Default constructor. The system does its main initialization in OnCreate (typical for ECS systems).

Methods

  • protected override void OnCreate() : System.Void
    Initializes internal state: sets up the m_DeletedQuery to track deleted entities with CustomName, caches PrefabSystem/PrefabUISystem/EndFrameBarrier references and constructs the m_Names dictionary.

  • protected override void OnUpdate() : System.Void
    Runs every frame (system update). If there are deleted entities with CustomName, removes their entries from m_Names. Uses a temporary NativeArray from the query and disposes it; safe-guards via try/finally.

  • public string GetDebugName(Entity entity) : System.String
    Returns a debug string including the prefab name (or obsolete ID / invalid prefab) and the entity index. Useful for logging and debugging.

  • public bool TryGetCustomName(Entity entity, out string customName) : System.Boolean
    Attempts to get a custom name from the m_Names dictionary. Returns true and out the name if present.

  • public void SetCustomName(Entity entity, string name) : System.Void
    Sets or clears an entity's custom name:

  • If passed Entity.Null or a blank/whitespace name, it removes the CustomName component (if present) via an EndFrameBarrier command buffer and removes the entry from m_Names.
  • If a non-empty name is provided, it updates m_Names and enqueues AddComponent and AddComponent so rendering/UI batches are updated.

  • If the passed entity is a Controller, the method maps it to its controlled entity (component.m_Controller) before making changes.

  • public string GetRenderedLabelName(Entity entity) : System.String
    Gets the string to render as a label: if a custom name exists, returns it; otherwise resolves the localization dictionary entry for the entity ID (via GetId) and returns either the localized value or the raw id if no localization entry exists.

  • public void BindNameForVirtualKeyboard(IJsonWriter writer, Entity entity) : System.Void
    Writes the Name value suitable for the virtual keyboard UI by calling writer.Write(GetNameForVirtualKeyboard(entity)).

  • public Name GetNameForVirtualKeyboard(Entity entity) : Name
    Produces a Name instance appropriate for the virtual keyboard. Special-cases transport lines to create a LocalizedName with a route-specific locale id; maps controllers to their controller entity and falls back to LocalizedName(GetId(...)).

  • public void BindName(IJsonWriter writer, Entity entity) : System.Void
    Writes the Name returned by GetName(entity) to the provided IJsonWriter. Used for UI binding where the UI expects Name types.

  • public Name GetName(Entity entity, bool omitBrand = false) : Name
    The primary method that resolves the name for an entity. Behavior summary:

  • Maps Controllers to their controlled entity.
  • Returns custom names (Name.CustomName) if present.
  • Handles CompanyData (returns brand name).
  • Handles spawnable buildings: formats addresses, optionally including brand.
  • Resolves transport stop names (marker/static stops).
  • Resolves route names for TransportLine entities (formatted with route number).
  • Resolves citizen/resident names with formatted localization entries (uses household, random localization, gendered localization where applicable).

  • For generic cases returns Name.LocalizedName(GetId(entity)).

  • private string GetGenderedLastNameId(Entity household, bool male) : System.String
    Resolves a household's gendered last-name localization ID. If the household prefab uses RandomGenderedLocalization and has a RandomLocalizationIndex buffer, appends the index via LocalizationUtils.AppendIndex; otherwise returns GetId(household) or null if household is Entity.Null.

  • public void BindFamilyName(IJsonWriter writer, Entity household) : System.Void
    Writes a Name for the household family name by calling GetFamilyName and writer.Write(...).

  • private Name GetFamilyName(Entity household) : Name
    Returns the family name for a household. If a custom name exists on the household returns that; otherwise computes male/female composition from HouseholdCitizen buffer to determine gendered last name ID.

  • private string GetId(Entity entity, bool useRandomLocalization = true) : System.String
    Resolves the localization or title ID for an entity:

  • If entity has a PrefabRef, resolves the referenced prefab (or zone prefab for spawnables).
  • For BrandData/ChirperAccountData uses the entity itself as the localization source.
  • If a Prefab has a Localization component, returns the localization ID (and if useRandomLocalization is true and a RandomLocalization buffer exists on the entity, appends the random index).
  • Otherwise asks PrefabUISystem for titleId.

  • If prefab cannot be retrieved, falls back to obsolete ID name via PrefabSystem.GetObsoleteID(...).GetName().

  • private Name GetCitizenName(Entity entity, Entity prefab) : Name
    Formats a citizen name using "Assets.CITIZEN_NAME_FORMAT" and FIRST_NAME / LAST_NAME arguments. Uses household data and gender to pick last name.

  • private Name GetResidentName(Entity entity, Entity prefab) : Name
    Generates a resident/creature name using pseudo-random seeds stored on the entity and localization index counts on the creature prefab. Creates a formatted name using the citizen name format and chosen localized first/last names.

  • private Name GetSpawnableBuildingName(Entity building, Entity zone, bool omitBrand = false) : Name
    Resolves an address-based name for a spawned building:

  • Uses BuildingUtils.GetAddress to get road and number.
  • Uses custom name for road if present; otherwise GetId(road).
  • If brand should be included (non-residential zones) and a brand is present, returns a formatted name using "Assets.NAMED_ADDRESS_NAME_FORMAT".

  • Otherwise falls back to "Assets.ADDRESS_NAME_FORMAT" with ROAD/NUMBER.

  • private string GetBrandId(Entity building) : System.String
    Searches the building's Renter buffer for a Renter that is a company and returns the company's brand id via GetId(component.m_Brand). Returns null if none found.

  • private Name GetStaticTransportStopName(Entity stop) : Name
    Formats a stop name using the stop's address (ROAD + NUMBER) if possible; otherwise returns a localized name via GetId(stop).

  • private Name GetMarkerTransportStopName(Entity stop) : Name
    Traverses up to 8 Owner components to find the owner entity and returns Name.LocalizedName(GetId(ownerEntity)). Used for marker-based stops.

  • private Name GetRouteName(Entity route, Entity prefab) : Name
    Creates a formatted Name for a route using the RoutePrefab.m_LocaleID combined with the prefab name and the route number (RouteNumber component).

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter : System.Void
    Serializes the m_Names dictionary to the provided writer: writes the count and then each Entity key and string value. Used for saving the game state.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader : System.Void
    Deserializes m_Names: reads the count, clears m_Names and reads each (Entity, string) pair, ignoring Entity.Null keys.

  • public void SetDefaults(Context context) : System.Void
    Called to set default state for the system (clears the m_Names dictionary).

Usage Example

// Example: assign a custom name to an entity (e.g., a building entity)
NameSystem nameSystem = World.GetOrCreateSystemManaged<NameSystem>();
nameSystem.SetCustomName(buildingEntity, "Bob's Bakery");

// Remove a custom name (pass empty or whitespace string)
nameSystem.SetCustomName(buildingEntity, "");

// Get a Name struct for UI binding
Name nameForUI = nameSystem.GetName(buildingEntity);

Notes and tips: - Use SetCustomName to create or remove custom names. The system enqueues component changes using EndFrameBarrier, so the actual ECS component changes occur at end-of-frame. - Use BindName / BindNameForVirtualKeyboard when writing JSON to UI writers; these will emit the appropriate Name representation (custom/localized/formatted) expected by the UI. - The Name struct supports both JSON binding (IJsonWriter.Write) and binary serialization (IWriter/IReader). Formatted names use key/value pairs (map) for format arguments. - The system relies on PrefabSystem and PrefabUISystem; if those systems are unavailable or a prefab is obsolete/missing, GetId falls back to obsolete ID names.