RuntimeInitializeOnLoad

Custom attribute that forces static constructor execution for marked classes at application startup. Scans all Paragon assemblies via reflection and calls RuntimeHelpers.RunClassConstructor for each decorated type.

Definition

Namespace: Paragon Assembly: Paragon.dll

[AttributeUsage(AttributeTargets.Class)]
public class RuntimeInitializeOnLoadAttribute : Attribute

Inheritance: Attribute → RuntimeInitializeOnLoadAttribute

Remarks

Unity's built-in [RuntimeInitializeOnLoadMethod] attribute works on static methods — it calls a specific method at startup. However, there is no built-in way to force a static constructor (class initializer) to run at startup for static classes.

RuntimeInitializeOnLoadAttribute fills this gap. It provides a class-level attribute that, combined with a [RuntimeInitializeOnLoadMethod] bootstrap method inside the attribute itself, forces all marked classes to have their static constructors executed during application initialization.

How It Works

1. The Initialize() method is decorated with Unity's [RuntimeInitializeOnLoadMethod], so Unity calls it automatically at startup

2. Initialize() scans all loaded assemblies whose name starts with "Paragon"

3. For each assembly, it finds all types decorated with [RuntimeInitializeOnLoad]

4. For each matching type, it calls RuntimeHelpers.RunClassConstructor(type.TypeHandle), which executes the type's static constructor if it hasn't already run

Why This Exists

Static classes with initialization logic (e.g., ParagonPaths) need their static constructors to run before any code references them. Without this attribute, a static constructor only runs when the class is first accessed — which may be too late if initialization order matters.

By marking a class with [RuntimeInitializeOnLoad], you guarantee its static constructor runs during the application startup phase, before gameplay code executes.

Quick Lookup

Goal	How
Force static ctor at startup	Decorate class with [RuntimeInitializeOnLoad]
Scope	Only scans assemblies starting with "Paragon"
Mechanism	RuntimeHelpers.RunClassConstructor(type.TypeHandle)
Trigger	Unity's [RuntimeInitializeOnLoadMethod] on the internal Initialize() method

Methods

Initialize (private static)

Bootstrap method called by Unity at startup. Scans Paragon assemblies and forces static constructors.

[RuntimeInitializeOnLoadMethod]
static void Initialize()

Algorithm:

AppDomain.CurrentDomain.GetAssemblies()
    .Where(assembly => assembly.FullName.StartsWith("Paragon"))
    .SelectMany(assembly => assembly.GetTypes())
    .Where(type => type.IsDefined(typeof(RuntimeInitializeOnLoadAttribute)))
    .ForEach(type => RuntimeHelpers.RunClassConstructor(type.TypeHandle));

Common Pitfalls

Only works for Paragon assemblies The Initialize() method filters assemblies by FullName.StartsWith("Paragon"). Classes in assemblies with different names (e.g., Townskeep, third-party) will not be scanned. If you need this behavior in game assemblies, ensure the assembly name starts with "Paragon" or add additional assembly filters.

No guaranteed order between decorated classes The order in which RuntimeHelpers.RunClassConstructor is called across multiple [RuntimeInitializeOnLoad] classes is determined by assembly load order and GetTypes() enumeration. Do not rely on one decorated class being initialized before another.

Static constructor exceptions halt initialization If a static constructor throws an exception, it will propagate through RunClassConstructor and may prevent subsequent classes from being initialized. Ensure static constructors are exception-safe.

Class-level only The attribute has AttributeTargets.Class, so it cannot be applied to structs, methods, or other targets. It is designed for static classes with static constructors.

Idempotent RuntimeHelpers.RunClassConstructor is safe to call on a type whose static constructor has already run — it becomes a no-op. There is no risk of double-initialization.

Examples

Basic Usage

using Paragon;

[RuntimeInitializeOnLoad]
public static class GameConfig
{
    public static readonly string ServerUrl;
    public static readonly int MaxPlayers;

    static GameConfig()
    {
        // This runs automatically at application startup
        ServerUrl = "https://api.example.com";
        MaxPlayers = 32;
        UnityEngine.Debug.Log("GameConfig initialized!");
    }
}

Static Service Registration

using Paragon;

[RuntimeInitializeOnLoad]
public static class ServiceLocator
{
    private static readonly Dictionary<Type, object> services;

    static ServiceLocator()
    {
        // Guaranteed to run at startup, before any service lookups
        services = new Dictionary<Type, object>();
        RegisterDefaults();
    }

    public static void Register<T>(T service) => services[typeof(T)] = service;
    public static T Get<T>() => (T)services[typeof(T)];

    private static void RegisterDefaults()
    {
        // Register default service implementations
    }
}

Comparison with Unity's Built-in Attribute

// Unity's built-in — works on static METHODS
public static class MySystem
{
    [UnityEngine.RuntimeInitializeOnLoadMethod]
    static void Initialize()
    {
        // Called at startup
    }
}

// Paragon's attribute — works on static CLASSES (forces static constructor)
[Paragon.RuntimeInitializeOnLoad]
public static class MyOtherSystem
{
    static MyOtherSystem()
    {
        // Called at startup automatically
    }
}

See Also

• ParagonPaths — uses this attribute for startup initialization

• Utility Overview — system overview

• PlayerLoopInjector — another low-level startup system