Skip to main content

8.7 - Extension Methods

As a game developer, you'll often work with classes and types that you didn't create yourself—whether they're part of the .NET framework, the Unity engine, or third-party libraries. Sometimes, you might wish these types had additional methods to make your code cleaner or more efficient. Extension methods solve this problem by allowing you to "add" methods to existing types without modifying their source code.

What Are Extension Methods?​

Extension methods are a C# feature that enables you to add methods to existing types without:

  • Creating a derived class
  • Modifying the original type's source code
  • Recompiling the original type

They appear as if they were instance methods of the extended type, making your code more readable and intuitive.

Basic Syntax​

To create an extension method:

  1. Define a static class to contain the extension methods
  2. Create a static method with the first parameter preceded by the this keyword
  3. The type of the first parameter is the type you're extending
// Extension methods for the string type
public static class StringExtensions
{
    // Extension method that counts words in a string
    public static int CountWords(this string str)
    {
        if (string.IsNullOrWhiteSpace(str))
            return 0;
            
        return str.Split(new[] { ' ', '\t', '\n' }, StringSplitOptions.RemoveEmptyEntries).Length;
    }
    
    // Extension method that checks if a string is a valid email
    public static bool IsValidEmail(this string str)
    {
        // Simple validation for demonstration
        return !string.IsNullOrEmpty(str) && str.Contains("@") && str.Contains(".");
    }
}

Using Extension Methods​

Once defined, you can use extension methods as if they were instance methods of the extended type:

string description = "This is a game description.";
int wordCount = description.CountWords(); // 5

string userInput = "player@example.com";
bool isValid = userInput.IsValidEmail(); // true

The compiler transforms these calls into static method calls behind the scenes, but the syntax makes your code more readable and object-oriented.

Extending Unity Types​

Extension methods are particularly useful in Unity development, where you often work with engine types that you can't modify. Let's look at some practical examples:

Extending Transform​

public static class TransformExtensions
{
    // Reset position, rotation, and scale
    public static void Reset(this Transform transform)
    {
        transform.position = Vector3.zero;
        transform.rotation = Quaternion.identity;
        transform.localScale = Vector3.one;
    }
    
    // Set position on specific axes only
    public static void SetPositionX(this Transform transform, float x)
    {
        Vector3 position = transform.position;
        position.x = x;
        transform.position = position;
    }
    
    public static void SetPositionY(this Transform transform, float y)
    {
        Vector3 position = transform.position;
        position.y = y;
        transform.position = position;
    }
    
    public static void SetPositionZ(this Transform transform, float z)
    {
        Vector3 position = transform.position;
        position.z = z;
        transform.position = position;
    }
    
    // Look at target but only on the Y axis (common for characters)
    public static void LookAtY(this Transform transform, Vector3 target)
    {
        Vector3 direction = target - transform.position;
        direction.y = 0;
        
        if (direction != Vector3.zero)
            transform.rotation = Quaternion.LookRotation(direction);
    }
}

Extending GameObject​

public static class GameObjectExtensions
{
    // Get component or add it if it doesn't exist
    public static T GetOrAddComponent<T>(this GameObject gameObject) where T : Component
    {
        T component = gameObject.GetComponent<T>();
        if (component == null)
            component = gameObject.AddComponent<T>();
        return component;
    }
    
    // Set layer for this object and all children
    public static void SetLayerRecursively(this GameObject gameObject, int layer)
    {
        gameObject.layer = layer;
        
        foreach (Transform child in gameObject.transform)
        {
            child.gameObject.SetLayerRecursively(layer);
        }
    }
    
    // Find a child by name (with optional recursive search)
    public static Transform FindChildRecursive(this GameObject gameObject, string childName)
    {
        Transform child = gameObject.transform.Find(childName);
        if (child != null)
            return child;
            
        foreach (Transform transform in gameObject.transform)
        {
            child = transform.gameObject.FindChildRecursive(childName);
            if (child != null)
                return child;
        }
        
        return null;
    }
}

Extending Vector3​

public static class Vector3Extensions
{
    // Get a random point within a specified radius
    public static Vector3 RandomPointInRadius(this Vector3 center, float radius)
    {
        Vector3 randomDirection = Random.insideUnitSphere * radius;
        return center + randomDirection;
    }
    
    // Get a flattened vector (y = 0)
    public static Vector3 Flatten(this Vector3 vector)
    {
        return new Vector3(vector.x, 0, vector.z);
    }
    
    // Check if a point is within a specified distance
    public static bool IsWithinDistance(this Vector3 point, Vector3 other, float maxDistance)
    {
        return Vector3.Distance(point, other) <= maxDistance;
    }
}

Extending Collections​

Extension methods are particularly useful for adding functionality to collection types:

public static class CollectionExtensions
{
    // Get a random element from a list
    public static T GetRandom<T>(this List<T> list)
    {
        if (list == null || list.Count == 0)
            return default;
            
        int randomIndex = Random.Range(0, list.Count);
        return list[randomIndex];
    }
    
    // Shuffle a list (Fisher-Yates algorithm)
    public static void Shuffle<T>(this List<T> list)
    {
        int n = list.Count;
        for (int i = n - 1; i > 0; i--)
        {
            int j = Random.Range(0, i + 1);
            T temp = list[i];
            list[i] = list[j];
            list[j] = temp;
        }
    }
    
    // Add a range of items to a dictionary
    public static void AddRange<TKey, TValue>(
        this Dictionary<TKey, TValue> dictionary, 
        IEnumerable<KeyValuePair<TKey, TValue>> items)
    {
        foreach (var item in items)
        {
            dictionary[item.Key] = item.Value;
        }
    }
}

Practical Example: Game Utility Extensions​

Let's create a set of extension methods that would be useful in a typical game project:

public static class GameExtensions
{
    // String extensions for game text
    public static string Bold(this string text)
    {
        return $"<b>{text}</b>";
    }
    
    public static string Colored(this string text, string htmlColor)
    {
        return $"<color={htmlColor}>{text}</color>";
    }
    
    // Float extensions for common game math
    public static float Remap(this float value, float fromMin, float fromMax, float toMin, float toMax)
    {
        return toMin + (value - fromMin) * (toMax - toMin) / (fromMax - fromMin);
    }
    
    // Transform extensions for common game operations
    public static void DestroyChildren(this Transform transform)
    {
        for (int i = transform.childCount - 1; i >= 0; i--)
        {
            Object.Destroy(transform.GetChild(i).gameObject);
        }
    }
    
    // RectTransform extensions for UI
    public static void SetAnchoredPositionX(this RectTransform rectTransform, float x)
    {
        Vector2 position = rectTransform.anchoredPosition;
        position.x = x;
        rectTransform.anchoredPosition = position;
    }
    
    public static void SetAnchoredPositionY(this RectTransform rectTransform, float y)
    {
        Vector2 position = rectTransform.anchoredPosition;
        position.y = y;
        rectTransform.anchoredPosition = position;
    }
    
    // Component extensions
    public static void SetActiveIfNotNull<T>(this T component, bool active) where T : Component
    {
        if (component != null && component.gameObject != null)
            component.gameObject.SetActive(active);
    }
}

Extension Methods vs. Inheritance​

You might wonder when to use extension methods versus inheritance. Here's a comparison:

Use Extension Methods When:​

  1. You can't modify the source type (e.g., sealed classes, types from external libraries)
  2. You want to add utility methods that don't fundamentally change the type's behavior
  3. You want to organize related functionality that applies to multiple types
  4. You want to avoid deep inheritance hierarchies

Use Inheritance When:​

  1. You need to override existing behavior
  2. You're adding significant new state (fields) along with behavior
  3. You're creating a specialized version of a base type
  4. You want polymorphic behavior

Limitations of Extension Methods​

Extension methods have some important limitations to be aware of:

  1. Can't access private members: Extension methods can only access public or internal members of the extended type.

  2. No overriding: Extension methods cannot override existing methods in the extended type.

  3. No extension properties: C# doesn't support extension properties, indexers, or events.

  4. No extension operators: You can't define extension operator overloads.

  5. Resolution order: Instance methods are always preferred over extension methods with the same signature.

Best Practices for Extension Methods​

  1. Use meaningful names: Extension method names should clearly indicate what they do and be consistent with the naming conventions of the extended type.

  2. Keep methods focused: Each extension method should do one thing well.

  3. Group related extensions: Organize related extension methods in the same static class.

  4. Consider null checks: Include null checks in your extension methods to avoid NullReferenceExceptions.

  5. Document your extensions: Use XML comments to document your extension methods, especially if they're part of a shared library.

  6. Don't abuse extension methods: Not everything needs to be an extension method. Use them judiciously for operations that conceptually belong to the extended type.

Extension Methods in Unity​

Unity developers commonly use extension methods to:

  1. Simplify common operations: Adding shortcuts for frequent operations like finding components or manipulating transforms.

  2. Add missing functionality: Adding methods that "should" exist on Unity types but don't.

  3. Create fluent interfaces: Enabling method chaining for more readable code.

  4. Implement utility functions: Adding general-purpose utilities that work across multiple Unity types.

Unity Relevance

Extension methods are widely used in Unity development to enhance the engine's API. Many popular Unity packages and frameworks, like DOTween and UniRx, make extensive use of extension methods to provide more intuitive interfaces.

Conclusion​

Extension methods are a powerful C# feature that allows you to enhance existing types with new functionality without modifying their source code. In game development, they're particularly valuable for adding utility methods to Unity's built-in types, creating more readable and maintainable code.

By organizing related functionality into well-designed extension methods, you can create a more expressive and intuitive API for your game code, making it easier to write, read, and maintain.

In the next section, we'll explore enums, which provide a way to define named constants and work with sets of related values.