Skip to content

Game.Prefabs.BuildingPrefab

Assembly: Game
Namespace: Game.Prefabs

Type: class

Base: StaticObjectPrefab

Summary:
Represents the prefab definition for building objects in the game. This prefab class defines building-specific configuration (access type, lot size fields), and participates in creating the ECS archetype and component set used to instantiate building entities. It overrides prefab/archetype collection methods to ensure building-related components are present, and it supports adding service upgrades which modify the archetype when needed.

Fields

  • public BuildingAccessType m_AccessType
    Defines how the building can be accessed (e.g., by road, pedestrian, special access rules). This is a public field set on the prefab asset and typically exposed in the editor.

  • public int m_LotWidth = 4
    [CustomField(typeof(BuildingLotWidthField))]
    Lot width in tiles/units for the building's footprint. The CustomField attribute indicates this uses a custom editor field in the content editor. Default value in the prefab is 4.

  • public int m_LotDepth = 4
    [CustomField(typeof(BuildingLotDepthField))]
    Lot depth in tiles/units for the building's footprint. The CustomField attribute indicates this uses a custom editor field in the content editor. Default value in the prefab is 4.

Properties

  • public int lotSize { get; }
    Computed read-only property that returns the total lot size as m_LotWidth * m_LotDepth. Useful for logic that needs the total footprint area (for zoning, placement, performance heuristics, etc).

Constructors

  • public BuildingPrefab()
    Default constructor (inherited behavior). Prefab instances are normally created/loaded by the game's asset/prefab system; you do not usually construct this directly in gameplay code.

Methods

  • public override void GetPrefabComponents(HashSet<ComponentType> components)
    Collects ECS component types that should be present on the "prefab" entity (components that describe the prefab asset itself). This implementation calls base and then ensures BuildingData, PlaceableObjectData, BuildingTerraformData and Effect are included. Use: ensures the prefab entity stores the expected data components for building prefabs.

  • public override void GetArchetypeComponents(HashSet<ComponentType> components)
    Collects ECS component types that will be present on runtime building instances (archetype components). This method calls base and adds the standard set of components used by buildings (Building, CitizenPresence, SpawnLocationElement, CurrentDistrict, UpdateFrame, color/surface, modifiers, policies, sub-lane/sub-objects, lot data and enabled effects). This list is what determines the runtime behavior and systems that will process building entities.

  • protected override void RefreshArchetype(EntityManager entityManager, Entity entity)
    When the prefab's enabled component set changes (for example when upgrades are added or removed), this method rebuilds the archetype for the prefab entity. It:

  • Collects components from attached prefab components (via GetComponents).
  • Adds extra component types when the prefab has BuildingUpgradeElement (InstalledUpgrade, SubNet, SubRoute).
  • Adds standard Created/Updated flags.

  • Creates a new archetype with PrefabUtils.ToArray(hashSet) and writes it into the prefab's ObjectData.m_Archetype via SetComponentData. This is critical to keep the prefab's archetype in sync with dynamic changes (upgrades) so instances created from the prefab get the correct component layout.

  • public void AddUpgrade(EntityManager entityManager, ServiceUpgrade upgrade)
    Adds upgrade support to this prefab: it finds the prefab entity (via PrefabSystem.TryGetEntity for this prefab instance) and, if the prefab entity doesn't already have BuildingUpgradeElement, it adds a buffer and refreshes the archetype if an archetype is already set. If the prefab entity cannot be found, it throws an Exception. Typical usage is to call this when a building gains optional upgrades (service upgrades) so the prefab and its archetype include the necessary components/buffers for runtime upgrading.

Usage Example

// Example: Add a service upgrade to a BuildingPrefab during mod initialization.
// 'world' is the Unity.Entities.World, 'entityManager' is world.EntityManager,
// 'serviceUpgrade' is a ServiceUpgrade object you want to enable for the prefab.

var prefabSystem = world.GetExistingSystemManaged<PrefabSystem>();
if (prefabSystem.TryGetPrefab<BuildingPrefab>("MyCustomBuildingPrefabName", out var buildingPrefab))
{
    // This will find the prefab's entity and ensure it has a BuildingUpgradeElement buffer
    // and refresh the archetype if necessary.
    buildingPrefab.AddUpgrade(entityManager, serviceUpgrade);
}
else
{
    // Prefab not loaded/registered yet — handle accordingly (defer until prefab is available).
}

Notes and modding tips: - BuildingPrefab participates in the game's ECS-based prefab system. Changes to a prefab's component set require RefreshArchetype so instantiated entities get the correct archetype layout. - The CustomField attributes on m_LotWidth/m_LotDepth indicate editor UI customization; these fields affect placement and should match tile-based sizing used by placement/terraforming systems. - AddUpgrade expects a valid EntityManager and that the prefab has been registered in the PrefabSystem. Calling AddUpgrade before the prefab entity exists will throw — use PrefabSystem to obtain the entity or defer until the prefab is ready.