Game.Simulation.SimulationUtils

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: public static class SimulationUtils

Base: System.Object

Summary:
Utility helper class containing simulation timing constants and small helper methods used by the game's update/tick scheduling and service request handling logic. Provides constants for update group counts, dispatch intervals, update group indices for various object/service types, and helper functions to compute which update subgroup should be executed on a given frame. Also contains helpers to manage backoff/cooldown logic for ServiceRequest instances.

Fields

public const float FRAMES_PER_SECOND
Frames per second used by the simulation (60.0).
public const int MOVING_OBJECT_UPDATE_GROUP_SHIFT
Bit shift used when grouping moving object updates.
public const int MOVING_OBJECT_UPDATE_GROUP_COUNT
Number of update groups for moving objects (16).
public const int NET_UPDATE_GROUP_COUNT
Number of network update groups (16).
public const int LANE_UPDATE_GROUP_COUNT
Number of lane update groups (16).
public const int TREE_UPDATE_GROUP_COUNT
Number of tree update groups (16).
public const int BUILDING_UPDATE_GROUP_COUNT
Number of building update groups (16).
public const int COMPANY_UPDATE_GROUP_COUNT
Number of company update groups (16).
public const int HOUSEHOLD_UPDATE_GROUP_COUNT
Number of household update groups (16).
public const int CITIZEN_UPDATE_GROUP_COUNT
Number of citizen update groups (16).
public const int HOUSEHOLDPET_UPDATE_GROUP_COUNT
Number of household pet update groups (16).
public const int GARBAGE_COLLECTION_DISPATCH_GROUP_COUNT
Number of groups used for garbage collection dispatch (32).
public const int TRANSPORT_VEHICLE_DISPATCH_GROUP_COUNT
Dispatch groups for transport vehicles (8).
public const int RANDOM_TRAFFIC_DISPATCH_GROUP_COUNT
Dispatch groups for random traffic (16).
public const int FIRE_RESCUE_DISPATCH_GROUP_COUNT
Dispatch groups for fire/rescue (4).
public const int POLICE_PATROL_DISPATCH_GROUP_COUNT
Dispatch groups for police patrol (32).
public const int TAXI_DISPATCH_GROUP_COUNT
Dispatch groups for taxis (16).
public const int HEALTHCARE_DISPATCH_GROUP_COUNT
Dispatch groups for healthcare (16).
public const int MAINTENANCE_DISPATCH_GROUP_COUNT
Dispatch groups for maintenance (32).
public const int POST_VAN_DISPATCH_GROUP_COUNT
Dispatch groups for post vans (32).
public const int MAIL_TRANSFER_DISPATCH_GROUP_COUNT
Dispatch groups for mail transfer (8).
public const int POLICE_EMERGENCY_DISPATCH_GROUP_COUNT
Dispatch groups for police emergency (4).
public const int EVACUATION_DISPATCH_GROUP_COUNT
Dispatch groups for evacuation (4).
public const int PRISONER_TRANSPORT_DISPATCH_GROUP_COUNT
Dispatch groups for prisoner transport (16).
public const int GARBAGE_TRANSFER_DISPATCH_GROUP_COUNT
Dispatch groups for garbage transfer (8).
public const int MOVING_OBJECT_INTERPOLATION_FRAME_COUNT
Number of interpolation frames for moving objects (4).
public const int MOVING_EVENT_INTERPOLATION_FRAME_COUNT
Interpolation frame count for moving events (4).
public const int AMBULANCE_UPDATE_GROUP
Update group index for ambulances (0).
public const int BUS_UPDATE_GROUP
Update group index for buses (1).
public const int GARBAGE_TRUCK_UPDATE_GROUP
Update group index for garbage trucks (2).
public const int TRAIN_UPDATE_GROUP
Update group index for trains (3).
public const int FIRE_ENGINE_UPDATE_GROUP
Update group index for fire engines (4).
public const int POLICE_CAR_UPDATE_GROUP
Update group index for police cars (5).
public const int TAXI_UPDATE_GROUP
Update group index for taxis (6).
public const int MAINTENANCE_VEHICLE_UPDATE_GROUP
Update group index for maintenance vehicles (7).
public const int WATERCRAFT_UPDATE_GROUP
Update group index for watercraft (8).
public const int POST_VAN_UPDATE_GROUP
Update group index for post vans (9).
public const int AIRCRAFT_UPDATE_GROUP
Update group index for aircraft (10).
public const int HEARSE_UPDATE_GROUP
Update group index for hearses (11).
public const int WORK_VEHICLE_UPDATE_GROUP
Update group index for general work vehicles (12).
public const int PET_UPDATE_GROUP
Update group index for pets (5) — shares value with police car group in this mapping.
public const int WILDLIFE_UPDATE_GROUP
Update group index for wildlife (13).
public const int DOMESTICATED_UPDATE_GROUP
Update group index for domesticated animals (9) — shares value with post van group.
public const uint BUILDING_UPDATE_INTERVAL
Interval (in frames) for building updates (16).
public const uint DISPATCH_INTERVAL
Interval for dispatch logic (16).
public const uint DISPATCH_DELAY
Dispatch delay value (64).
public const uint MAX_PATHFIND_DELAY
Maximum delay for pathfinding retries (64).
public const uint CREATURE_SPAWN_INTERVAL
Interval for creature spawn updates (16).
public const uint MOVING_EVENT_UPDATE_INTERVAL
Interval for moving event updates (16).
public const uint MOVING_EVENT_UPDATE_GROUP
Moving event update group index (0).
public const int TRANSPORT_STATION_UPDATE_GROUP
Update group index for transport stations (0).
public const int HOSPITAL_UPDATE_GROUP
Update group index for hospitals (1).
public const int TRANSPORT_DEPOT_UPDATE_GROUP
Update group index for transport depots (2).
public const int GARBAGE_FACILITY_UPDATE_GROUP
Update group index for garbage facilities (5).
public const int SCHOOL_UPDATE_GROUP
Update group index for schools (6).
public const int FIRE_STATION_UPDATE_GROUP
Update group index for fire stations (7).
public const int POLICE_STATION_UPDATE_GROUP
Update group index for police stations (8).
public const int PARK_UPDATE_GROUP
Update group index for parks (9).
public const int MAINTENANCE_DEPOT_UPDATE_GROUP
Update group index for maintenance depots (10).
public const int POST_FACILITY_UPDATE_GROUP
Update group index for post facilities (11).
public const int PARKING_FACILITY_UPDATE_GROUP
Update group index for parking facilities (12).
public const int TELECOM_FACILITY_UPDATE_GROUP
Update group index for telecom facilities (13).
public const int EXTRACTOR_FACILITY_UPDATE_GROUP
Update group index for extractor facilities (14).
public const int EMERGENCY_SHELTER_UPDATE_GROUP
Update group index for emergency shelters (15).
public const int DISASTER_FACILITY_UPDATE_GROUP
Update group index for disaster facilities (0).
public const int FIREWATCH_TOWER_UPDATE_GROUP
Update group index for firewatch towers (1).
public const int DEATHCARE_FACILITY_UPDATE_GROUP
Update group index for deathcare facilities (2).
public const int PRISON_UPDATE_GROUP
Update group index for prisons (3).
public const int ADMIN_BUILDING_UPDATE_GROUP
Update group index for administrative buildings (4).
public const int WELFARE_OFFICE_UPDATE_GROUP
Update group index for welfare offices (5).
public const int RESEARCH_FACILITY_UPDATE_GROUP
Update group index for research facilities (6).

Properties

None (static utility class — no instance properties).

Constructors

None (static utility class, no constructors to instantiate).

Methods

public static uint GetUpdateFrameWithInterval(uint frame, uint interval, int groupCount)
Returns the subgroup index for a given frame when updates are spaced using a fixed interval. Calculation: (frame / interval) & (groupCount - 1). Useful to spread work evenly across subgroups when using a fixed interval.
Parameters:
- frame: Current frame number.
- interval: Interval in frames between updates.
- groupCount: Number of subgroups to mask with.
Returns: subgroup index (uint).
public static uint GetUpdateFrame(uint frame, int updatesPerDay, int groupCount)
Computes the subgroup index for updates that are scheduled a certain number of times per in-game day. Internally uses 262,144 as the number of simulation ticks per day and divides accordingly. Uses bitmasking to confine result to groupCount.
Parameters:
- frame: Current frame number.
- updatesPerDay: How many updates per simulated day.
- groupCount: Number of subgroups.
Returns: subgroup index (uint).
public static uint GetUpdateFrameRare(uint frame, int daysPerUpdate, int groupCount)
Like GetUpdateFrame but for rare updates that occur once every N days. Computes which subgroup should run based on daysPerUpdate.
Parameters:
- frame: Current frame number.
- daysPerUpdate: Number of in-game days between updates.
- groupCount: Number of subgroups.
Returns: subgroup index (uint).
public static void ResetFailedRequest(ref ServiceRequest serviceRequest)
Handles exponential backoff for a failing service request. Increments the request's fail count (saturates at 255) and sets a cooldown determined by 2^(min(8, failCount)) - 1. This produces rapidly increasing cooldowns but clamps after 8 increments.
Parameters:
- serviceRequest: reference to the ServiceRequest struct to modify.
Behavior:
- Increments m_FailCount up to 255.
- Sets m_Cooldown to (1 << min(8, m_FailCount)) - 1 (cast to byte).
public static void ResetReverseRequest(ref ServiceRequest serviceRequest)
Similar to ResetFailedRequest but guarantees a minimum cooldown of 4 frames. This is used for reversals where a slightly longer minimum cooldown is desired.
Parameters:
- serviceRequest: reference to the ServiceRequest struct to modify.
Behavior:
- Increments m_FailCount up to 255.
- Sets m_Cooldown to max(4, (1 << min(8, m_FailCount)) - 1) (cast to byte).
public static bool TickServiceRequest(ref ServiceRequest serviceRequest)
Ticks down the cooldown on a ServiceRequest and returns whether the request should be processed this tick. The request is allowed to be processed if cooldown is zero or the SkipCooldown flag is present. Also clears the SkipCooldown flag after checking and decrements cooldown by 1 (not below 0).
Parameters:
- serviceRequest: reference to the ServiceRequest struct to modify.
Returns:
- bool: true if the request may be processed this tick; false otherwise.
Notes:
- Uses math.max(0, cooldown - 1) when decrementing.
- Clears ServiceRequestFlags.SkipCooldown from the request's flags after checking.

Additional notes about ServiceRequest usage: - ServiceRequest is expected to be a struct containing at least: - byte m_FailCount — number of consecutive failures (used to compute exponential backoff). - byte m_Cooldown — cooldown counter in frames. - ServiceRequestFlags m_Flags — bitflags (used to signal SkipCooldown). - ServiceRequestFlags.SkipCooldown indicates that the request should bypass cooldown for one tick; TickServiceRequest clears this flag after honoring it.

Usage Example

// Example: compute which subgroup to update this frame
uint frame = 123456u;
int groupCount = SimulationUtils.MOVING_OBJECT_UPDATE_GROUP_COUNT;
uint subgroup = SimulationUtils.GetUpdateFrameWithInterval(frame, SimulationUtils.BUILDING_UPDATE_INTERVAL, groupCount);

// Example: manage a ServiceRequest's backoff/cooldown
ServiceRequest req = default;

// On a failure:
SimulationUtils.ResetFailedRequest(ref req);

// On a reverse failure (use a minimum cooldown)
SimulationUtils.ResetReverseRequest(ref req);

// Each tick, decide if we should process the request:
if (SimulationUtils.TickServiceRequest(ref req))
{
    // process the request this frame
}