Skip to content

Game.Settings.ScreenResolution

Assembly:
Assembly-CSharp (Assembly-CSharp.dll)

Namespace:
Game.Settings

Type:
struct (value type)

Base:
IEquatable, IComparable, IJsonReadable, IJsonWritable

Summary:
Represents a screen resolution including width, height and a rational refresh rate. Provides equality and comparison semantics, JSON (de)serialization support via Colossal's IJsonReader/IJsonWriter, and helper methods to ensure the values are usable on the running platform. Commonly used for saving/loading user display settings and for comparing available resolutions in Cities: Skylines 2 mods.

Fields

  • public int width
    Width in pixels for this resolution.

  • public int height
    Height in pixels for this resolution.

  • public RefreshRate refreshRate
    Refresh rate represented as a rational number (numerator/denominator). The RefreshRate type exposes .numerator, .denominator and a .value (floating Hz) property.

Properties

  • public double refreshRateDelta => Math.Abs(Math.Round(refreshRate.value) - refreshRate.value)
    Difference between the refresh rate value and the nearest integer. Useful to detect non-integer refresh rates (e.g., fractional Hz) or to determine whether rounding to an integer is safe.

  • public bool isValid
    True when width and height are positive and refreshRate numerator/denominator are non-zero. Use this to verify that the struct represents a usable resolution.

Constructors

  • public ScreenResolution(Resolution resolution)
    Constructs a ScreenResolution from a UnityEngine.Resolution instance, copying width, height and the resolution.refreshRateRatio.

  • (implicit) default parameterless constructor
    As a struct, a default instance exists where numeric fields default to 0; such an instance will not be isValid until populated and/or sanitized.

Methods

  • private static void SupportValueTypesForAOT()
    Internal helper that registers the types with Colossal's JSON AOT support: JSON.SupportTypeForAOT() and JSON.SupportTypeForAOT(). This is used to ensure JSON (de)serialization works correctly on AOT platforms.

  • public bool Equals(ScreenResolution other)
    Value equality comparing width, height and refreshRate (numerator and denominator). Used by IEquatable.

  • public override bool Equals(object obj)
    Object override that forwards to the strongly-typed Equals when possible.

  • public override int GetHashCode()
    Returns a hash code based on the tuple (width, height, refreshRate).

  • public static bool operator ==(ScreenResolution left, ScreenResolution right)
    Equality operator that calls Equals.

  • public static bool operator !=(ScreenResolution left, ScreenResolution right)
    Inequality operator that negates Equals.

  • public void Sanitize()
    Ensures the refreshRate is valid. If refreshRate numerator/denominator are zero or refreshRate.value is NaN, the method replaces refreshRate with Screen.currentResolution.refreshRateRatio (the current platform resolution's refresh rate). Call this before applying or saving resolutions to avoid invalid refresh rates.

  • public int CompareTo(ScreenResolution other)
    Compares first by width, then height, then refreshRate.value. Useful for sorting available resolutions from smallest to largest (or vice versa when reversed).

  • public void Read(IJsonReader reader)
    Implements IJsonReadable. Expects a JSON map with properties "width", "height", "numerator", "denominator". Reads those into the struct fields. Matches the Write format.

  • public void Write(IJsonWriter writer)
    Implements IJsonWritable. Writes a typed JSON object and writes properties "width", "height", "numerator", "denominator". This is the format the game's settings JSON uses for resolutions.

  • public override string ToString()
    Returns a human-readable representation in the format: "{width}x{height}x{refreshRate.value}Hz" (e.g., "1920x1080x59.94Hz").

Usage Example

// Create from the current Unity resolution and ensure it's usable.
ScreenResolution res = new ScreenResolution(Screen.currentResolution);
res.Sanitize();
Debug.Log(res.ToString()); // e.g. "1920x1080x60Hz"

// Compare two resolutions
ScreenResolution a = new ScreenResolution(new Resolution { width = 1920, height = 1080, refreshRateRatio = Screen.currentResolution.refreshRateRatio });
ScreenResolution b = new ScreenResolution(new Resolution { width = 2560, height = 1440, refreshRateRatio = Screen.currentResolution.refreshRateRatio });
int cmp = a.CompareTo(b); // negative => a < b

// JSON serialization (using game's IJsonWriter/IJsonReader):
// Writer side (pseudo-usage; actual writer is provided by Colossal framework)
IJsonWriter writer = /* get writer from framework */;
a.Write(writer);

// Reader side (pseudo-usage):
IJsonReader reader = /* get reader from framework */;
ScreenResolution loaded = new ScreenResolution();
loaded.Read(reader);
loaded.Sanitize(); // sanitize after loading to ensure a valid refresh rate

Notes: - The Read/Write pair serializes only width, height and the refresh rate numerator/denominator. If you need compatibility with other JSON formats, convert accordingly. - RefreshRate.value is a floating-point representation derived from numerator/denominator; use refreshRateDelta to detect whether it is (nearly) an integer.