Skip to content

Game.Input.Usages

Assembly: Game
Namespace: Game.Input

Type: struct

Base: System.ValueType

Summary:
Usages is a compact, bitset-like struct used to represent a set of named "usages" (flags) for input contexts in Cities: Skylines 2. It maps string usage names to integer indices and stores the enabled usages in an array of 64-bit buckets (ulong[]). The type supports read-only mode, combining/intersecting usage sets, enumerating enabled usages, and serializing to NameAndParameters. It's used by the input system to determine which usage contexts (e.g., Menu, Tool, Overlay) are active for devices, actions or bindings.

Fields

  • private ulong[] m_Value
    Holds the bit buckets representing enabled usages. Each ulong stores 64 usage flags. Null/empty array indicates no usages set. Manipulated by indexers and set operations.

  • private bool m_ReadOnly
    If true, modifying operations (indexer set, SetFrom, MakeEditable checks) throw InvalidOperationException. Used to enforce immutable/default usage sets.

  • public const string kMenuUsage
    Constant usage name "Menu". Also present for many built-in usage names below.

  • public const string kDefaultUsage
    Constant usage name "DefaultTool".

  • public const string kOverlayUsage
    Constant usage name "Overlay".

  • public const string kToolUsage
    Constant usage name "Tool".

  • public const string kCancelableToolUsage
    Constant usage name "CancelableTool".

  • public const string kDebugUsage
    Constant usage name "Debug".

  • public const string kEditorUsage
    Constant usage name "Editor".

  • public const string kPhotoModeUsage
    Constant usage name "PhotoMode".

  • public const string kOptionsUsage
    Constant usage name "Options".

  • public const string kTutorialUsage
    Constant usage name "Tutorial".

  • public const string kDiscardableToolUsage
    Constant usage name "DiscardableTool".

  • public class Comparer (nested)
    Nested comparer type providing equality and hashcode logic for Usages. See below for its members.

  • public static readonly Comparer defaultComparer (inside Comparer)
    A ready-to-use instance of the nested Comparer for comparing two Usages instances by their underlying bit arrays.

Properties

  • internal static Dictionary<string, int> usagesMap { get; }
    A global mapping from usage name string to integer index. New usages are assigned an increasing integer index via AddOrGetUsage. Internal so mods within the same assembly / internals-visible code can access it.

  • public static Usages defaultUsages { get; }
    A predefined Usages instance representing the built-in default set (constructed from BuiltInUsages.DefaultSet). Usually read-only.

  • public static Usages empty
    Returns an empty, read-only Usages (no usages set).

  • public bool this[int index]
    Integer indexer to get/set the usage flag at the given index. Uses bit arithmetic on m_Value (index >> 6 selects bucket, bit offset index & 63). Setting when m_ReadOnly is true throws InvalidOperationException. Setting true will expand m_Value as needed.

  • public bool this[string usage]
    String indexer that maps the usage name through usagesMap (AddOrGetUsage when setting) to the integer indexer. Getting returns false if name not present in the map.

  • public bool isReadOnly
    Returns true if the instance is read-only.

  • public bool isNone
    True when no usages are set (m_Value null or all buckets zero).

  • public NameAndParameters parameters
    Provides a NameAndParameters representation (name = "Usages") with parameters listing all enabled usages as NamedValue entries. The setter accepts a NameAndParameters and applies any numeric-named parameters to the corresponding integer usage indices.

Constructors

  • public Usages(int length = 0, bool readOnly = true)
    Creates an instance with a given number of 64-bit buckets (length). If length == 0 an empty array is used. readOnly defaults to true. Use a non-zero length to preallocate capacity for bit flags.

  • public Usages(bool readOnly = true, params int[] values)
    Creates a Usages from explicit integer indices. It preallocates using values.Max() and sets each given index to true. The instance's read-only state is set to the provided value.

  • public Usages(BuiltInUsages usages, bool readOnly = true)
    Constructs a Usages from a BuiltInUsages enum (bitmask of known built-in usages). It sets built-in usage names (Menu, Tool, etc.) according to the enum flags. readOnly controls whether the instance is immutable.

  • internal Usages(bool readOnly = true, params string[] customUsages)
    Internal constructor that accepts string usage names and marks those usages enabled (adding them to usagesMap). Useful for creating custom named usage sets.

Methods

  • public Usages Copy(bool readOnly = true)
    Returns a (shallow) copy. If the current instance is already read-only and readOnly is true, returns the same instance. Otherwise creates a new Usages with copied m_Value and the requested readOnly flag.

  • public void SetFrom(Usages source)
    Copies the bitset from another Usages into this one. Throws InvalidOperationException if this instance is read-only. Resizes m_Value to accommodate source if needed.

  • internal void MakeReadOnly()
    Marks the instance read-only (m_ReadOnly = true).

  • internal void MakeEditable()
    Marks the instance editable (m_ReadOnly = false).

  • public static bool TestAny(Usages usages1, Usages usages2)
    Returns true if usages1 and usages2 share at least one enabled usage (bitwise AND of buckets has any non-zero).

  • public static bool TestAll(Usages usages1, Usages usages2)
    Returns true if usages1 and usages2 have equal enabled bits across buckets (used to test equality of the used set).

  • public static Usages Intersect(Usages usages1, Usages usages2, bool readOnly = true)
    Returns a new Usages representing the bitwise AND of the two inputs.

  • public static Usages Combine(Usages usages1, Usages usages2, bool readOnly = true)
    Returns a new Usages representing the bitwise OR (union) of the two inputs.

  • internal static int AddOrGetUsage(string usageName)
    Adds a usage name to usagesMap if missing and returns its integer index. This is the canonical way to get an index for a string usage.

  • IEnumerator<int> IEnumerable<int>.GetEnumerator()
    Generic enumerator returning all enabled usage indices. Implemented via Enumerate().

  • public IEnumerator GetEnumerator()
    Non-generic enumerator wrapper. Implemented via Enumerate().

  • private IEnumerable<int> Enumerate()
    Iterator implementation that yields all enabled usage indices by scanning each bucket and each bit (0..63).

  • public bool Equals(Usages other)
    Equality using the nested Comparer (compares bit arrays across lengths).

  • public override string ToString()
    Returns a pipe-separated list of enabled usage integer indices (using the enumerator) or "Empty" when m_Value is null.

  • Nested Comparer methods:

  • public bool Equals(Usages x, Usages y)
    Compares two Usages by comparing corresponding buckets; treats missing buckets as zero.
  • public int GetHashCode(Usages usages)
    Computes a HashCode by adding each ulong bucket value.

Usage Example

// Create a Usages instance with specific integer indices:
var u1 = new Game.Input.Usages(readOnly: false, 0, 1, 10);
u1.MakeReadOnly();

// Use built-in default usages:
var defaults = Game.Input.Usages.defaultUsages;

// Check a usage by name (string indexer). Adds name to the map if setting.
bool menuActive = defaults["Menu"];
// Enable a custom usage:
var custom = new Game.Input.Usages(readOnly: false, "MyModTool");
custom["MyModTool"] = true;

// Combine two sets:
var combined = Game.Input.Usages.Combine(defaults, custom);

// Intersect:
var common = Game.Input.Usages.Intersect(defaults, combined);

// Iterate enabled usage indices:
foreach (int usageIndex in combined)
{
    Debug.Log("Enabled usage index: " + usageIndex);
}

// Convert to NameAndParameters for serialization or binding:
var parameters = combined.parameters;

// Parse parameters back into a Usages instance:
var parsed = new Game.Input.Usages(readOnly: false);
parsed.parameters = parameters;