Skip to content

Game.Settings.Setting

Assembly:
Game (Game.dll)

Namespace:
Game.Settings

Type:
public abstract class

Base:
System.Object, System.IEquatable

Summary:
Base class for mod settings used by the SceneFlow / Game settings system. Provides common functionality for applying and saving settings, equality comparison based on public properties (with exclusions), utility helpers to find runtime camera and light components, and helpers to register the setting with the in-game Options UI. Intended to be subclassed to implement concrete setting groups and individual setting behaviour.

Fields

  • protected static ILog log
    Holds a logger instance obtained from Colossal.Logging.LogManager with the name "SceneFlow". Used by subclasses and methods to log verbose/debug information.

  • protected static SharedSettings settings
    Protected static property (backed as a property in source) that returns the current GameManager.instance?.settings. Convenience accessor for shared settings state; it may be null if GameManager.instance is not available.

  • [Exclude] protected internal virtual bool builtIn
    Virtual property marked with [Exclude]. Returns true by default. Indicates whether the setting is considered built-in. Subclasses can override to change this information.

  • public event OnSettingsAppliedHandler onSettingsApplied
    Event invoked when Apply() is called. Subscribers can react to settings being applied.

Properties

  • protected static SharedSettings settings { get; }
    Returns GameManager.instance?.settings. Safe to use to access the global SharedSettings instance if available; otherwise null.

  • [Exclude] protected internal virtual bool builtIn { get; }
    Indicates if a setting is built-in (default true). Can be overridden by subclasses; marked with Exclude (likely used by the serialization or UI system to skip this member).

Constructors

  • public Setting()
    Default constructor (implicit). As an abstract class, this provides the standard initialization for derived classes; no custom initialization is performed in the base class.

Methods

  • public bool Equals(Setting obj)
    Implements IEquatable. Calls the object overload of Equals for core comparison logic.

  • public override bool Equals(object obj)
    Compares this instance to another object for equality by reflecting over public instance properties. Behavior details:

  • Returns false if obj is null.
  • Returns true if both object references are identical.
  • If obj's runtime type is not assignable to this instance's type, returns false.
  • If a public instance property named "enabled" exists and this.enabled is false and both enabled values are equal, the method returns true (treats a disabled setting as equal regardless of other property differences).
  • Iterates all public instance properties and compares their values; properties annotated with IgnoreEqualsAttribute are skipped. If any comparable property's values differ, returns false.

  • If all compared properties are equal (or skipped), returns true.

  • public override int GetHashCode()
    Generates a hash code by iterating public instance properties and combining their value hash codes with an integer accumulator (num = (num * 937) ^ propertyValue.GetHashCode()). Note: this implementation assumes property values are non-null (calling GetHashCode() without null checks may throw if a property value is null).

  • protected bool TryGetGameplayCameraController(ref CameraController controller)
    Attempts to obtain the main gameplay CameraController. If the ref is already non-null it returns true. Otherwise it finds the GameObject tagged "GameplayCamera" and returns its CameraController component if present. Returns true and sets controller on success, otherwise sets controller to null and returns false.

  • protected bool TryGetGameplayCamera(ref HDAdditionalCameraData cameraData)
    Attempts to obtain HDAdditionalCameraData from Camera.main. If ref is already non-null returns true. Otherwise checks Camera.main and returns its HDAdditionalCameraData component if present. Returns false and sets cameraData to null on failure.

  • protected bool TryGetGameplayCamera(ref Camera camera)
    Attempts to obtain the main Camera. If the ref is already non-null returns true. Otherwise uses Camera.main and returns true if found, otherwise false.

  • protected bool TryGetSunLight(ref Light sunLight)
    Attempts to find the scene light GameObject tagged "SunLight" and returns its Light component. Returns true on success (sets sunLight), otherwise sets sunLight to null and returns false.

  • protected bool TryGetSunLightData(ref HDAdditionalLightData sunLightData)
    Attempts to find the scene light GameObject tagged "SunLight" and returns its HDAdditionalLightData component. Returns true on success, otherwise sets sunLightData to null and returns false.

  • public async void ApplyAndSave()
    Calls Apply() (invokes the onSettingsApplied event and related logic) and then asynchronously awaits AssetDatabase.global.SaveSettings(). Note: this is an async void method — exceptions thrown after await are not directly awaitable by callers and should be handled inside the method or by subscribed logging.

  • public virtual void Apply()
    Virtual method that performs application of settings. Default implementation logs a verbose message indicating settings are being applied for the concrete type and invokes the onSettingsApplied event (if any subscribers exist). Subclasses should override to apply concrete behavior but should call base.Apply() if they want to preserve the event invocation/logging.

  • public abstract void SetDefaults()
    Abstract method that must be implemented by subclasses to set default values for the setting's properties.

  • public virtual AutomaticSettings.SettingPageData GetPageData(string id, bool addPrefix)
    Provides page metadata for automatic UI generation. Default implementation delegates to AutomaticSettings.FillSettingsPage(this, id, addPrefix).

  • internal void RegisterInOptionsUI(string name, bool addPrefix = false)
    Instance helper that registers this setting instance into the game's Options UI using the provided name and optional prefix by calling the static RegisterInOptionsUI.

  • internal static bool RegisterInOptionsUI(Setting instance, string name, bool addPrefix)
    Static helper that looks up the OptionsUISystem from World.DefaultGameObjectInjectionWorld and, if present, registers the provided setting instance. Returns true on success, false if the OptionsUISystem isn't available.

  • internal static bool UnregisterInOptionsUI(string name)
    Static helper that looks up the OptionsUISystem from World.DefaultGameObjectInjectionWorld and, if present, unregisters settings by the provided name. Returns true on success, false if the OptionsUISystem isn't available.

Usage Example

// Example subclass that implements a concrete setting group
public class MyGraphicsSetting : Setting
{
    public bool enabled { get; set; }
    public float intensity { get; set; }

    public override void SetDefaults()
    {
        enabled = true;
        intensity = 1.0f;
    }

    public override void Apply()
    {
        base.Apply(); // preserves logging and onSettingsApplied invocation
        // Apply your graphics changes here, e.g. adjust a post-processing volume
        if (enabled)
        {
            // enable/adjust effect using intensity
        }
    }
}

// Registering the setting in the options UI at runtime:
var mySetting = new MyGraphicsSetting();
mySetting.SetDefaults();
MyGraphicsSetting.RegisterInOptionsUI(mySetting, "My Graphics", addPrefix: true);

// Apply and persist:
mySetting.ApplyAndSave();

Notes and caveats: - Equals uses reflection and ignores properties marked with IgnoreEqualsAttribute; if a public "enabled" property exists and the instance is disabled, the instance is considered equal to another instance whose enabled value matches (even if other properties differ). - GetHashCode assumes public property values are non-null; subclasses should ensure properties used in hashing are not null or override GetHashCode if null values are possible. - Several TryGet... helpers rely on GameObject tags ("GameplayCamera", "SunLight") and Camera.main, so they may fail in non-standard scenes or during early initialization. Registration into the Options UI requires the ECS World DefaultGameObjectInjectionWorld and the OptionsUISystem to be available.