EllanJiang/GameFramework · error · GameFrameworkException

You must set screen DPI first.

Error message

You must set screen DPI first.

What it means

Utility.Converter's pixel-to-centimeter conversion divides by the static ScreenDpi property. If ScreenDpi has not been set (or is <= 0), the conversion is meaningless, so GetCentimetersFromPixels throws "You must set screen DPI first."

Solutions

1. Set Utility.ScreenDpi = Screen.dpi (or a device-appropriate fallback) at startup.
2. Guard calls so conversions only happen after DPI initialization.
3. Fall back to a sensible default DPI (e.g. 96 or 160) when Screen.dpi reports 0.

Example fix

// before
float cm = Utility.GetCentimetersFromPixels(pixels); // DPI not set

// after
if (Utility.ScreenDpi <= 0)
{
    Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f;
}
float cm = Utility.GetCentimetersFromPixels(pixels);

if (Utility.ScreenDpi <= 0) { Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f; }

try { float cm = Utility.GetCentimetersFromPixels(px); } catch (GameFrameworkException) { Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f; }

When it happens

Trigger: Calling Utility.GetCentimetersFromPixels(pixels) before setting Utility.ScreenDpi to a positive value.

Common situations: Calling conversion helpers during app startup before the DPI bootstrap code runs, or after forgetting to set DPI on a platform where Screen.dpi is unavailable/zero.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Load resource agent helper is invalid.
• Object pool manager is invalid.
• Resource helper is invalid.
• Resource loader is invalid.
• Resource manager is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/b3b5980ca1a8b5ec. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Utility/Utility.Converter.cs:52

            /// <summary>
            /// 获取或设置屏幕每英寸点数。
            /// </summary>
            public static float ScreenDpi
            {
                get;
                set;
            }

            /// <summary>
            /// 将像素转换为厘米。
            /// </summary>
            /// <param name="pixels">像素。</param>
            /// <returns>厘米。</returns>
            public static float GetCentimetersFromPixels(float pixels)
            {
                if (ScreenDpi <= 0)
                {
                    throw new GameFrameworkException("You must set screen DPI first.");
                }

                return InchesToCentimeters * pixels / ScreenDpi;
            }

            /// <summary>
            /// 将厘米转换为像素。
            /// </summary>
            /// <param name="centimeters">厘米。</param>
            /// <returns>像素。</returns>
            public static float GetPixelsFromCentimeters(float centimeters)
            {
                if (ScreenDpi <= 0)
                {
                    throw new GameFrameworkException("You must set screen DPI first.");
                }

                return CentimetersToInches * centimeters * ScreenDpi;

View on GitHub (pinned to d0c010b051)