memory-management

What this skill does

# Memory Management

## Memory Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    GAME MEMORY LAYOUT                        │
├─────────────────────────────────────────────────────────────┤
│  STACK (Fast, Auto-managed):                                 │
│  ├─ Local variables                                         │
│  ├─ Function parameters                                     │
│  └─ Return addresses                                        │
│                                                              │
│  HEAP (Slower, Manual/GC-managed):                           │
│  ├─ Dynamic allocations (new/malloc)                        │
│  ├─ Game objects                                            │
│  └─ Asset data                                              │
│                                                              │
│  STATIC (Fixed at compile time):                             │
│  ├─ Global variables                                        │
│  ├─ Static class members                                    │
│  └─ Constant data                                           │
│                                                              │
│  VRAM (GPU Memory):                                          │
│  ├─ Textures                                                │
│  ├─ Meshes                                                  │
│  └─ Render targets                                          │
└─────────────────────────────────────────────────────────────┘
```

## Platform Memory Budgets

```
MEMORY BUDGET GUIDELINES:
┌─────────────────────────────────────────────────────────────┐
│  PLATFORM      │ TOTAL    │ GAME LOGIC │ ASSETS   │ BUFFER │
├────────────────┼──────────┼────────────┼──────────┼────────┤
│  Mobile Low    │ 512 MB   │ 50 MB      │ 350 MB   │ 112 MB │
│  Mobile High   │ 2 GB     │ 200 MB     │ 1.5 GB   │ 300 MB │
│  Console       │ 8 GB     │ 500 MB     │ 6 GB     │ 1.5 GB │
│  PC Min        │ 4 GB     │ 300 MB     │ 3 GB     │ 700 MB │
│  PC High       │ 16 GB    │ 1 GB       │ 12 GB    │ 3 GB   │
│  VR            │ 8 GB     │ 400 MB     │ 6 GB     │ 1.6 GB │
└────────────────┴──────────┴────────────┴──────────┴────────┘

VRAM BUDGETS:
┌─────────────────────────────────────────────────────────────┐
│  Mobile:    512 MB - 1 GB                                   │
│  Console:   8-12 GB (shared with RAM)                       │
│  PC Low:    2-4 GB                                          │
│  PC High:   8-16 GB                                         │
└─────────────────────────────────────────────────────────────┘
```

## Object Pooling

```csharp
// ✅ Production-Ready: Generic Object Pool
public class ObjectPool<T> where T : class
{
    private readonly Stack<T> _pool;
    private readonly Func<T> _createFunc;
    private readonly Action<T> _onGet;
    private readonly Action<T> _onReturn;
    private readonly int _maxSize;

    public int CountActive { get; private set; }
    public int CountInPool => _pool.Count;

    public ObjectPool(
        Func<T> createFunc,
        Action<T> onGet = null,
        Action<T> onReturn = null,
        int initialSize = 10,
        int maxSize = 100)
    {
        _createFunc = createFunc;
        _onGet = onGet;
        _onReturn = onReturn;
        _maxSize = maxSize;
        _pool = new Stack<T>(initialSize);

        // Pre-warm pool
        for (int i = 0; i < initialSize; i++)
        {
            _pool.Push(_createFunc());
        }
    }

    public T Get()
    {
        T item = _pool.Count > 0 ? _pool.Pop() : _createFunc();
        _onGet?.Invoke(item);
        CountActive++;
        return item;
    }

    public void Return(T item)
    {
        if (item == null) return;

        _onReturn?.Invoke(item);
        CountActive--;

        if (_pool.Count < _maxSize)
        {
            _pool.Push(item);
        }
        // If pool is full, let GC collect the item
    }

    public void Clear()
    {
        _pool.Clear();
        CountActive = 0;
    }
}

// Usage Example: Bullet Pool
public class BulletManager : MonoBehaviour
{
    private ObjectPool<Bullet> _bulletPool;

    void Awake()
    {
        _bulletPool = new ObjectPool<Bullet>(
            createFunc: () => Instantiate(bulletPrefab).GetComponent<Bullet>(),
            onGet: bullet => bullet.gameObject.SetActive(true),
            onReturn: bullet => bullet.gameObject.SetActive(false),
            initialSize: 50,
            maxSize: 200
        );
    }

    public Bullet SpawnBullet(Vector3 position, Vector3 direction)
    {
        var bullet = _bulletPool.Get();
        bullet.Initialize(position, direction);
        bullet.OnDestroyed += () => _bulletPool.Return(bullet);
        return bullet;
    }
}
```

## Garbage Collection Optimization

```
GC SPIKE PREVENTION:
┌─────────────────────────────────────────────────────────────┐
│  AVOID IN UPDATE/HOT PATHS:                                  │
│  ✗ new object()                                             │
│  ✗ string concatenation ("a" + "b")                         │
│  ✗ LINQ queries (ToList(), Where(), etc.)                   │
│  ✗ Boxing value types                                       │
│  ✗ Closures/lambdas capturing variables                     │
│  ✗ foreach on non-struct enumerators                        │
│                                                              │
│  DO INSTEAD:                                                 │
│  ✓ Object pooling                                           │
│  ✓ StringBuilder for strings                                │
│  ✓ Pre-allocated collections                                │
│  ✓ Struct-based data                                        │
│  ✓ Cache delegates                                          │
│  ✓ for loops with index                                     │
└─────────────────────────────────────────────────────────────┘
```

```csharp
// ✅ Production-Ready: Allocation-Free Patterns
public class AllocationFreePatterns
{
    // ❌ BAD: Allocates every frame
    void BadUpdate()
    {
        string status = "Health: " + health + "/" + maxHealth; // Allocates
        var enemies = allEntities.Where(e => e.IsEnemy).ToList(); // Allocates
        foreach (var enemy in enemies) { } // May allocate enumerator
    }

    // ✓ GOOD: Zero allocations
    private StringBuilder _sb = new StringBuilder(64);
    private List<Entity> _enemyCache = new List<Entity>(100);

    void GoodUpdate()
    {
        // Reuse StringBuilder
        _sb.Clear();
        _sb.Append("Health: ").Append(health).Append("/").Append(maxHealth);

        // Reuse list, avoid LINQ
        _enemyCache.Clear();
        for (int i = 0; i < allEntities.Count; i++)
        {
            if (allEntities[i].IsEnemy)
                _enemyCache.Add(allEntities[i]);
        }

        // Index-based iteration
        for (int i = 0; i < _enemyCache.Count; i++)
        {
            ProcessEnemy(_enemyCache[i]);
        }
    }
}
```

## Memory Profiling

```
PROFILING WORKFLOW:
┌─────────────────────────────────────────────────────────────┐
│  1. BASELINE: Measure memory at known state                 │
│     → Startup, menu, gameplay, level transition            │
│                                                              │
│  2. MONITOR: Track over time                                │
│     → Memory growth indicates leaks                         │
│     → Spikes indicate heavy allocations                    │
│                                                              │
│  3. SNAPSHOT: Capture heap at suspicious moments            │
│     → Compare snapshots to find what's growing             │
│                                                              │
│  4. TRACE: Find allocation source                           │
│     → Stack trace shows where allocation happened          │
│     → Identify hot paths                                   │
│