Skip to content

Game.Buildings.BuildingUtils

Assembly: Game
Namespace: Game.Buildings

Type: public static class

Base: System.Object

Summary:
Utility helper methods and data structures for building-related calculations and gameplay logic in Cities: Skylines 2. BuildingUtils contains math helpers (corner/position/height sampling), efficiency calculation and factor helpers, lot/upgrade/terraform handling, address resolution for roads, random outside-connection selection, collapse/maintenance utilities, and helpers for homeless/shelter logic and vehicle capacity. These functions are intended for use by systems and mods that need to inspect or manipulate building-related data at the entity/component level.

Fields

  • public struct LotInfo
    Nested value type describing a building lot's geometry and height constraints. Members include:
  • m_Position : float3 — world-space center of the lot.
  • m_Extents : float2 — half-extents of the lot in local X/Z.
  • m_Radius : float — length of the extents vector.
  • m_Circular : float — flag-like float indicating circular geometry.
  • m_Rotation : quaternion — lot rotation.
  • m_FrontHeights, m_RightHeights, m_BackHeights, m_LeftHeights : float3 — control heights used for Bezier interpolation along each side.
  • m_FlatX0, m_FlatZ0, m_FlatX1, m_FlatZ1 : float3 — flat/terrace limits offsets for lot edges.

  • m_MinLimit, m_MaxLimit : float4 — min/max height limits for smoothing/terraform constraints.

  • public const float MAX_ROAD_CONNECTION_DISTANCE = 8.4f
    Maximum distance used when computing road connection offsets / address numbers.

  • public const float GEOMETRY_SIZE_OFFSET = 0.4f
    Offset used in geometry sizing calculations.

  • public const float MIN_BUILDING_HEIGHT = 5f
    Minimum building height used in some building logic.

  • public const float MIN_CONSTRUCTION_HEIGHT = 15f
    Minimum height threshold used for construction logic.

  • public const float RANDOM_CONSTRUCTION_HEIGHT = 5f
    Randomized element used when computing construction height.

  • public const float COLLAPSE_ACCELERATION = 5f
    Acceleration constant used for collapse time/height calculations.

Properties

  • None (static utility class — no properties).

Constructors

  • None (static utility class — no instance constructors).

Methods

  • public static Quad3 CalculateCorners(Game.Objects.Transform transform, int2 lotSize)
    Calculate the world-space quad corners of a lot given transform and lot size (lotSize * 4 units).

  • public static Quad3 CalculateCorners(float3 position, quaternion rotation, float2 halfLotSize)
    Calculate the quad corners using position, rotation and half extents.

  • public static float3 CalculateFrontPosition(Game.Objects.Transform transform, int lotDepth)
    Returns the world position at the front of a building based on its transform and lot depth.

  • public static float GetEfficiency(BufferAccessor<Efficiency> bufferAccessor, int i)
    Get efficiency from a BufferAccessor entry or return 1 if buffer is empty.

  • public static float GetImmediateEfficiency(BufferAccessor<Efficiency> bufferAccessor, int i)
    Get immediate (non-delayed) efficiency from a BufferAccessor entry or return 1 if empty.

  • public static float GetEfficiency(Entity entity, ref BufferLookup<Efficiency> bufferLookup)
    Get combined efficiency for an entity by reading its Efficiency buffer (returns 1 if none).

  • public static float GetEfficiency(DynamicBuffer<Efficiency> buffer)
    Combine all efficiency factors in a DynamicBuffer into a single efficiency multiplier (rounded to 2 decimals and clamped to >= 0.01 when >0).

  • public static float GetImmediateEfficiency(DynamicBuffer<Efficiency> buffer)
    Combine only immediate efficiency factors (excludes some factors like non-immediate ones) from the buffer.

  • public static float GetEfficiency(Span<float> factors)
    Combine an array/span of factor floats into a single efficiency (same rounding/clamping semantics).

  • public static void GetEfficiencyFactors(DynamicBuffer<Efficiency> buffer, Span<float> factors)
    Populate a provided span with efficiency factors indexed by EfficiencyFactor; missing entries set to 1.

  • public static void SetEfficiencyFactors(DynamicBuffer<Efficiency> buffer, Span<float> factors)
    Replace buffer contents with Efficiency entries for factors that differ from 1 (within tolerance).

  • public static void SetEfficiencyFactor(DynamicBuffer<Efficiency> buffer, EfficiencyFactor factor, float efficiency)
    Set a single efficiency factor in the buffer (or remove it if set back to ~1).

  • public static float2 ApproximateEfficiencyFactors(float targetEfficiency, float2 weights)
    Solve for two factor modifiers whose weighted product approximates targetEfficiency. Handles degenerate weights/targets, with assertions.

  • public static float4 ApproximateEfficiencyFactors(float targetEfficiency, float4 weights)
    Iteratively solve (binary search) for four factor modifiers to reach the target efficiency given weights.

  • public static float GetEfficiency(byte rawValue)
    Convert a byte-encoded efficiency (0..100) to float (0..1).

  • public static int GetLevelingCost(AreaType areaType, BuildingPropertyData propertyData, int currentlevel, DynamicBuffer<CityModifier> cityEffects)
    Calculate cost to level up a building based on area type, property data, current level and city modifiers.

  • public static AreaType GetAreaType(Entity buildPrefab, ref ComponentLookup<SpawnableBuildingData> spawnableBuildingDatas, ref ComponentLookup<ZoneData> zoneDatas)
    Determine the zone/area type of a build prefab (Residential/Commercial/Industrial/None).

  • public static bool CheckOption(Building building, BuildingOption option)
    Check whether a Building's option bitmask includes a given option.

  • public static bool CheckOption(InstalledUpgrade installedUpgrade, BuildingOption option)
    Check whether an InstalledUpgrade's option mask includes a given option.

  • public static void ApplyModifier(ref float value, DynamicBuffer<BuildingModifier> modifiers, BuildingModifierType type)
    Apply the delta (additive and multiplicative) from a BuildingModifier entry in a buffer to a float value.

  • public static bool HasOption(BuildingOptionData optionData, BuildingOption option)
    Check option mask on BuildingOptionData.

  • public static int GetVehicleCapacity(float efficiency, int capacity)
    Compute vehicle capacity scaled by efficiency and clamp to [1, capacity] when efficiency > small threshold, otherwise 0.

  • public static bool GetAddress(EntityManager entityManager, Entity entity, out Entity road, out int number)
    Resolve a building/attached entity to a road aggregate and an address number, using component data (overload that reads building/attached components).

  • public static bool GetAddress(EntityManager entityManager, Entity entity, Entity edge, float curvePos, out Entity road, out int number)
    Resolve address number when given an edge and curve position; accounts for roundabouts and front/back offsets of lots, returns road aggregate and computed address number.

  • public static bool GetRandomOutsideConnectionByParameters(ref NativeList<Entity> outsideConnections, ref ComponentLookup<OutsideConnectionData> outsideConnectionDatas, ref ComponentLookup<PrefabRef> prefabRefs, Unity.Mathematics.Random random, float4 outsideConnectionSpawnParameters, out Entity result)
    Choose a random outside connection entity based on spawn-type probabilities (road/train/air/ship) and then pick one matching the chosen transfer type.

  • public static bool GetRandomOutsideConnectionByTransferType(ref NativeList<Entity> outsideConnections, ref ComponentLookup<OutsideConnectionData> outsideConnectionDatas, ref ComponentLookup<PrefabRef> prefabRefs, Unity.Mathematics.Random random, OutsideConnectionTransferType ocTransferType, out Entity result)
    Choose a random outside-connection entity filtered by transfer type.

  • public static OutsideConnectionTransferType GetOutsideConnectionType(Entity building, ref ComponentLookup<PrefabRef> prefabRefs, ref ComponentLookup<OutsideConnectionData> outsideConnectionDatas)
    Returns the outside-connection transfer type supported by a building prefab (or None).

  • public static LotInfo CalculateLotInfo(float2 extents, Game.Objects.Transform transform, Game.Objects.Elevation elevation, Lot lot, PrefabRef prefabRef, DynamicBuffer<InstalledUpgrade> upgrades, ComponentLookup<Game.Objects.Transform> transforms, ComponentLookup<PrefabRef> prefabRefs, ComponentLookup<ObjectGeometryData> objectGeometryDatas, ComponentLookup<BuildingTerraformData> buildingTerraformDatas, ComponentLookup<BuildingExtensionData> buildingExtensionDatas, bool defaultNoSmooth, out bool hasExtensionLots)
    Construct LotInfo for a building prefab: computes extents, positional offsets, flat areas, min/max smoothing limits, takes installed upgrades (extensions) into account and reports if extensions change lot smoothing/limits.

  • public static float SampleHeight(ref LotInfo lotInfo, float3 position)
    Sample an interpolated height for a given world-space position relative to a lot (uses Bezier interpolation and flat/terrace limits in LotInfo). Returns world Y.

  • public static float GetCollapseTime(float height)
    Compute collapse time given height (sqrt-based formula).

  • public static float GetCollapseHeight(float time)
    Compute collapsed height for a given time (reverse formula).

  • public static MaintenanceType GetMaintenanceType(Entity entity, ref ComponentLookup<Park> parks, ref ComponentLookup<NetCondition> netConditions, ref ComponentLookup<Edge> edges, ref ComponentLookup<Surface> surfaces, ref ComponentLookup<Vehicle> vehicles)
    Determine maintenance type (Park, Snow, Road, Vehicle, None) for an entity by checking components and surface snow accumulation.

  • public static void CalculateUpgradeRangeValues(quaternion rotation, BuildingData ownerBuildingData, BuildingData buildingData, ServiceUpgradeData serviceUpgradeData, out float3 forward, out float width, out float length, out float roundness, out bool circular)
    Calculate forward direction and placement bounds for applying a service upgrade (placement distance, width/length and roundness). Takes lot orientations into account.

  • public static bool IsHomelessShelterBuilding(Entity propertyEntity, ref ComponentLookup<Park> parks, ref ComponentLookup<Abandoned> abandoneds)
    Returns whether a building acts as a homeless shelter (park or abandoned building).

  • public static bool IsHomelessShelterBuilding(EntityManager entityManager, Entity propertyEntity)
    Same as above but using EntityManager convenience check.

  • public static bool IsHomelessHousehold(Household household, Entity propertyEntity, ref ComponentLookup<Park> parks, ref ComponentLookup<Abandoned> abandoneds)
    Check if a Household object represents a homeless household (moved in flag + building shelter checks).

  • public static bool IsHomelessHousehold(EntityManager entityManager, Entity householdEntity)
    Check homeless status for a household entity (considers moved-in flag, moving-away, renter/property/abandoned flags).

  • public static Entity GetPropertyFromRenter(Entity renter, ref ComponentLookup<HomelessHousehold> homelessHouseholds, ref ComponentLookup<PropertyRenter> propertyRenters)
    Return property entity for a renter (temp home for homeless households or m_Property for renters), or Entity.Null.

  • public static Entity GetHouseholdHomeBuilding(Entity householdEntity, ref ComponentLookup<PropertyRenter> propertyRenters, ref ComponentLookup<HomelessHousehold> homelessHouseholds)
    Get the home building entity for a household (renter or homeless temp home).

  • public static Entity GetHouseholdHomeBuilding(Entity householdEntity, ref ComponentLookup<PropertyRenter> propertyRenters, ref ComponentLookup<HomelessHousehold> homelessHouseholds, ref ComponentLookup<TouristHousehold> touristHouseholds)
    Overload that also checks tourist households (resolves tourist hotel to m_Property if applicable).

  • public static int GetShelterHomelessCapacity(Entity buildingPrefabEntity, ref ComponentLookup<BuildingData> buildingDatas, ref ComponentLookup<BuildingPropertyData> buildingPropertyDatas)
    Compute capacity of a building prefab to shelter homeless households based on lot size and property data (residential property count, allowed resources, space multiplier, etc.).

Usage Example

// Example: sampling lot height from a prefab instance
public void ExampleSampleHeight(Entity buildingEntity,
                               ref ComponentLookup<Game.Objects.Transform> transforms,
                               ref ComponentLookup<PrefabRef> prefabRefs,
                               ref ComponentLookup<ObjectGeometryData> objectGeometryDatas,
                               ref ComponentLookup<BuildingTerraformData> buildingTerraformDatas,
                               ref ComponentLookup<BuildingExtensionData> buildingExtensionDatas,
                               ref DynamicBuffer<InstalledUpgrade> upgrades,
                               Lot lot)
{
    // Get transform and prefabRef for the building instance
    var transform = transforms[buildingEntity];
    var prefabRef = prefabRefs[buildingEntity];

    // Use an 8x8 extents example (half-extents)
    float2 extents = new float2(8f, 8f);

    // Compute LotInfo (requires many component lookups normally provided by systems)
    bool hasExtensionLots;
    var lotInfo = BuildingUtils.CalculateLotInfo(extents, transform, default, lot, prefabRef, upgrades,
                                                transforms, prefabRefs, objectGeometryDatas,
                                                buildingTerraformDatas, buildingExtensionDatas,
                                                defaultNoSmooth: false, out hasExtensionLots);

    // Sample height at a world position
    float3 worldPos = transform.m_Position + new float3(2f, 0f, 0f);
    float height = BuildingUtils.SampleHeight(ref lotInfo, worldPos);

    Debug.Log($"Sampled lot height: {height}, has extensions: {hasExtensionLots}");
}

If you want, I can generate a condensed API reference (only signatures) or a more detailed walkthrough for a specific method such as CalculateLotInfo / SampleHeight or the efficiency helpers.