Hardware and System Configuration

What the system is for

Every shipped game needs to know what it is running on. GPU model, VRAM budget, system RAM, connected displays and their refresh rates, locale, timezone and ray-tracing support are all facts that influence quality presets, analytics events and crash reports. Collecting them reliably and consistently is boilerplate that every project reinvents.

The System Configuration module in Serenity solves that once. It captures a structured snapshot during the initialization pipeline, keeps it in memory for the rest of the session and exposes it through typed interfaces that the rest of the framework already knows how to consume.

The Unity problem

Unity exposes hardware information through scattered static APIs — SystemInfo, Screen, Display and QualitySettings — spread across several namespaces with no agreed structure. Every project ends up with a different utility class, a different set of fields and a different moment for the collection to happen. When a crash report arrives, the hardware context is missing or incomplete. When adaptive quality needs to know how much VRAM is available, it reaches into SystemInfo directly and couples itself to Unity's API.

Without a dedicated module, hardware detection is duplicated, inconsistent and untestable. Fields are collected at the wrong moment, locale is read differently in different parts of the codebase and resolution changes during a session go undetected until the next restart.

How Serenity approaches it

Serenity exposes system configuration through ISystemConfigurationService, which combines ISystemConfigurationProvider for reading the snapshot and ISystemConfigurationSnapshotStore for persisting it. The snapshot itself is described by ISystemConfigurationSnapshot, a structured interface covering GpuName, GpuMemoryMB, SystemMemoryMB, SupportsRayTracing, SupportsComputeShaders, PrimaryDisplayWidth, PrimaryDisplayHeight, PrimaryDisplayRefreshRate, a Displays array of DisplayInfo entries, Language, CultureName, RegionDisplayName, TimeZoneId, OperatingSystem, DeviceModel and the UTC timestamp CollectedAtUtc.

Runtime resolution changes are handled by IResolutionChangeDetector, which caches a reference state and reports meaningful changes through HasMeaningfulChange. Settings are controlled by ISystemConfigurationSettings, covering when to collect (startup, focus change, resolution change, polling), which fields to include, ray-tracing detection mode, refresh rate source, display index and optional sync with Game Settings through SnapshotKeyMap.

How it fits into Serenity

System Configuration lives in the Serenity.SystemConfiguration namespace and follows the foundation's layered structure. The Domain layer defines DisplayInfo, enums such as RayTracingDetectionMode, RefreshRateSourceMode, CultureListSourceMode and PlatformMask, plus value objects like SnapshotKeyMap. The Application layer owns the service and snapshot interfaces, the snapshot store, the resolution change detector, the settings contract and the CollectSystemConfigurationTask that runs during the initialization pipeline. The Infrastructure layer provides the Unity implementations — UnitySystemConfigurationService, UnitySystemConfigurationSnapshot and UnityResolutionChangeDetector — behind the application interfaces so they can be replaced without touching consumers.

System Configuration cooperates with the Initialization Pipeline, which triggers the collection task at boot before any other system needs hardware data. It cooperates with Game Graphics, which reads the snapshot to select the initial quality preset. It cooperates with Game Settings through the SyncMap, so snapshot values can be written directly to settings keys. It cooperates with the Event Dispatcher and logging services for telemetry and crash reporting context.

Practical workflow

1. Configure ISystemConfigurationSettings to select which fields to include — hardware, display info, culture — and when to collect.
2. Set CollectOnStartup to true so the initialization pipeline runs CollectSystemConfigurationTask before any other system starts.
3. Optionally enable CollectOnFocusChange and CollectOnResolutionChange to refresh the snapshot when the environment changes.
4. Inject ISystemConfigurationService wherever adaptive quality, analytics or crash reporting need hardware context.
5. Use IResolutionChangeDetector if any system needs to react to display changes between snapshots.
6. Set up SyncMap in ISystemConfigurationSettings to push snapshot values — VRAM, resolution, refresh rate — into Game Settings keys automatically.

What you get

• Service interface ISystemConfigurationService combining provider and snapshot store
• Structured snapshot ISystemConfigurationSnapshot with GPU name, VRAM, RAM, ray-tracing and compute shader support
• Display list via DisplayInfo covering width, height, refresh rate and primary flag for every connected monitor
• Locale and timezone fields Language, CultureName, RegionDisplayName and TimeZoneId in every snapshot
• Resolution change detection through IResolutionChangeDetector with CacheCurrent and HasMeaningfulChange
• Configurable collection triggers: startup, focus change, resolution change and polling interval
• Game Settings sync via SnapshotKeyMap so hardware data flows into settings keys without manual bridging
• Replaceable Unity infrastructure behind domain interfaces for testability and platform flexibility

When to use this

• Projects that need reliable hardware context for adaptive quality presets from the first frame.
• Games that send analytics or crash reports and need a consistent, structured hardware payload.
• Projects with multiple display outputs where refresh rate and resolution must be tracked per monitor.
• Codebases that want locale and timezone captured at boot without duplicating SystemInfo calls across systems.

Related systems

• Graphics Settings System A graphics service that persists quality level, resolution and fullscreen state through Game Settings and broadcasts every change via the Event Dispatcher.
• Initialization Pipeline An ordered async pipeline that runs your Unity startup tasks with criticality levels, weighted progress and telemetry streaming to any loading screen.
• Game Settings Typed get and set use cases for bool, int, float and string settings, with persistence and update signals built in.
• Data Persistence Layer A port hierarchy that decouples save contracts from Unity backends so file storage, PlayerPrefs and encryption can all change without touching game code.