omgkit 2.13.0 → 2.15.0

package/plugin/skills/game/unity-patterns/SKILL.md

@@ -0,0 +1,488 @@
+# Unity Patterns
+
+Unity game architecture patterns including ECS, ScriptableObjects, object pooling, and performance optimization.
+
+## Overview
+
+Unity development patterns provide scalable, maintainable game architectures that optimize performance and enable team collaboration.
+
+## Core Concepts
+
+### Architecture Approaches
+- **MonoBehaviour**: Traditional Unity component
+- **ScriptableObjects**: Data containers, assets
+- **ECS (DOTS)**: Data-oriented, high performance
+- **Hybrid**: Mix of approaches
+
+### Design Patterns in Unity
+- Singleton (Service Locator)
+- Object Pool
+- State Machine
+- Observer (Events)
+- Command Pattern
+
+## ScriptableObjects Architecture
+
+### Data Definition
+```csharp
+// Weapon data container
+[CreateAssetMenu(fileName = "NewWeapon", menuName = "Game/Weapons/Weapon Data")]
+public class WeaponData : ScriptableObject
+{
+    [Header("Basic Info")]
+    public string weaponName;
+    public Sprite icon;
+    public GameObject prefab;
+
+    [Header("Stats")]
+    public float damage;
+    public float attackSpeed;
+    public float range;
+
+    [Header("Audio")]
+    public AudioClip attackSound;
+    public AudioClip hitSound;
+
+    public float DPS => damage * attackSpeed;
+}
+
+// Character stats
+[CreateAssetMenu(fileName = "NewCharacter", menuName = "Game/Characters/Character Data")]
+public class CharacterData : ScriptableObject
+{
+    public string characterName;
+    public int maxHealth;
+    public float moveSpeed;
+    public WeaponData defaultWeapon;
+
+    [SerializeField] private AnimatorOverrideController animatorOverride;
+
+    public void ApplyTo(Character character)
+    {
+        character.MaxHealth = maxHealth;
+        character.MoveSpeed = moveSpeed;
+        character.EquipWeapon(defaultWeapon);
+        if (animatorOverride != null)
+            character.Animator.runtimeAnimatorController = animatorOverride;
+    }
+}
+```
+
+### Event System with ScriptableObjects
+```csharp
+// Game event (no parameters)
+[CreateAssetMenu(menuName = "Events/Game Event")]
+public class GameEvent : ScriptableObject
+{
+    private readonly List<GameEventListener> listeners = new();
+
+    public void Raise()
+    {
+        for (int i = listeners.Count - 1; i >= 0; i--)
+            listeners[i].OnEventRaised();
+    }
+
+    public void RegisterListener(GameEventListener listener) => listeners.Add(listener);
+    public void UnregisterListener(GameEventListener listener) => listeners.Remove(listener);
+}
+
+// Listener component
+public class GameEventListener : MonoBehaviour
+{
+    public GameEvent gameEvent;
+    public UnityEvent response;
+
+    private void OnEnable() => gameEvent.RegisterListener(this);
+    private void OnDisable() => gameEvent.UnregisterListener(this);
+    public void OnEventRaised() => response.Invoke();
+}
+
+// Generic event with parameter
+[CreateAssetMenu(menuName = "Events/Int Event")]
+public class IntEvent : ScriptableObject
+{
+    private readonly List<IntEventListener> listeners = new();
+
+    public void Raise(int value)
+    {
+        foreach (var listener in listeners)
+            listener.OnEventRaised(value);
+    }
+
+    public void RegisterListener(IntEventListener listener) => listeners.Add(listener);
+    public void UnregisterListener(IntEventListener listener) => listeners.Remove(listener);
+}
+```
+
+## Object Pooling
+
+### Generic Pool System
+```csharp
+public class ObjectPool<T> where T : Component
+{
+    private readonly T prefab;
+    private readonly Transform parent;
+    private readonly Queue<T> pool = new();
+    private readonly HashSet<T> active = new();
+    private readonly int maxSize;
+
+    public ObjectPool(T prefab, Transform parent, int initialSize, int maxSize = 100)
+    {
+        this.prefab = prefab;
+        this.parent = parent;
+        this.maxSize = maxSize;
+
+        for (int i = 0; i < initialSize; i++)
+            CreateInstance();
+    }
+
+    private T CreateInstance()
+    {
+        var instance = Object.Instantiate(prefab, parent);
+        instance.gameObject.SetActive(false);
+        pool.Enqueue(instance);
+        return instance;
+    }
+
+    public T Get()
+    {
+        T instance;
+
+        if (pool.Count > 0)
+        {
+            instance = pool.Dequeue();
+        }
+        else if (active.Count < maxSize)
+        {
+            instance = CreateInstance();
+            pool.Dequeue();
+        }
+        else
+        {
+            Debug.LogWarning($"Pool exhausted for {prefab.name}");
+            return null;
+        }
+
+        instance.gameObject.SetActive(true);
+        active.Add(instance);
+        return instance;
+    }
+
+    public void Return(T instance)
+    {
+        if (!active.Contains(instance)) return;
+
+        instance.gameObject.SetActive(false);
+        active.Remove(instance);
+        pool.Enqueue(instance);
+    }
+
+    public void ReturnAll()
+    {
+        foreach (var instance in active.ToList())
+            Return(instance);
+    }
+}
+
+// Poolable interface
+public interface IPoolable
+{
+    void OnSpawn();
+    void OnDespawn();
+}
+
+// Usage example
+public class BulletPool : MonoBehaviour
+{
+    [SerializeField] private Bullet bulletPrefab;
+    [SerializeField] private int poolSize = 50;
+
+    private ObjectPool<Bullet> pool;
+
+    private void Awake()
+    {
+        pool = new ObjectPool<Bullet>(bulletPrefab, transform, poolSize);
+    }
+
+    public Bullet SpawnBullet(Vector3 position, Quaternion rotation)
+    {
+        var bullet = pool.Get();
+        if (bullet == null) return null;
+
+        bullet.transform.SetPositionAndRotation(position, rotation);
+        bullet.Initialize(this);
+        return bullet;
+    }
+
+    public void ReturnBullet(Bullet bullet) => pool.Return(bullet);
+}
+```
+
+## State Machine
+
+### Hierarchical State Machine
+```csharp
+public interface IState
+{
+    void Enter();
+    void Exit();
+    void Update();
+    void FixedUpdate();
+}
+
+public abstract class State : IState
+{
+    protected StateMachine stateMachine;
+    protected readonly float startTime;
+
+    protected State(StateMachine stateMachine)
+    {
+        this.stateMachine = stateMachine;
+        startTime = Time.time;
+    }
+
+    public virtual void Enter() { }
+    public virtual void Exit() { }
+    public virtual void Update() { }
+    public virtual void FixedUpdate() { }
+}
+
+public class StateMachine
+{
+    public IState CurrentState { get; private set; }
+    private readonly Dictionary<Type, IState> states = new();
+
+    public void AddState(IState state)
+    {
+        states[state.GetType()] = state;
+    }
+
+    public void ChangeState<T>() where T : IState
+    {
+        CurrentState?.Exit();
+        CurrentState = states[typeof(T)];
+        CurrentState.Enter();
+    }
+
+    public void Update() => CurrentState?.Update();
+    public void FixedUpdate() => CurrentState?.FixedUpdate();
+}
+
+// Character states
+public class IdleState : State
+{
+    private readonly CharacterController character;
+
+    public IdleState(StateMachine sm, CharacterController character) : base(sm)
+    {
+        this.character = character;
+    }
+
+    public override void Enter()
+    {
+        character.Animator.Play("Idle");
+    }
+
+    public override void Update()
+    {
+        if (character.Input.Movement.magnitude > 0.1f)
+            stateMachine.ChangeState<MoveState>();
+
+        if (character.Input.Attack)
+            stateMachine.ChangeState<AttackState>();
+    }
+}
+```
+
+## ECS (DOTS) Basics
+
+### Component Definition
+```csharp
+using Unity.Entities;
+using Unity.Mathematics;
+
+// Component data
+public struct Position : IComponentData
+{
+    public float3 Value;
+}
+
+public struct Velocity : IComponentData
+{
+    public float3 Value;
+}
+
+public struct Health : IComponentData
+{
+    public float Current;
+    public float Max;
+}
+
+// Buffer element
+[InternalBufferCapacity(8)]
+public struct DamageBuffer : IBufferElementData
+{
+    public float Amount;
+    public Entity Source;
+}
+```
+
+### System Implementation
+```csharp
+using Unity.Burst;
+using Unity.Entities;
+using Unity.Jobs;
+using Unity.Transforms;
+
+[BurstCompile]
+public partial struct MovementSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        float deltaTime = SystemAPI.Time.DeltaTime;
+
+        new MoveJob { DeltaTime = deltaTime }.ScheduleParallel();
+    }
+
+    [BurstCompile]
+    partial struct MoveJob : IJobEntity
+    {
+        public float DeltaTime;
+
+        void Execute(ref LocalTransform transform, in Velocity velocity)
+        {
+            transform.Position += velocity.Value * DeltaTime;
+        }
+    }
+}
+
+[BurstCompile]
+public partial struct DamageSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        var ecb = new EntityCommandBuffer(Allocator.Temp);
+
+        foreach (var (health, damageBuffer, entity) in
+            SystemAPI.Query<RefRW<Health>, DynamicBuffer<DamageBuffer>>()
+                .WithEntityAccess())
+        {
+            foreach (var damage in damageBuffer)
+            {
+                health.ValueRW.Current -= damage.Amount;
+            }
+
+            damageBuffer.Clear();
+
+            if (health.ValueRO.Current <= 0)
+            {
+                ecb.DestroyEntity(entity);
+            }
+        }
+
+        ecb.Playback(state.EntityManager);
+        ecb.Dispose();
+    }
+}
+```
+
+## Performance Optimization
+
+### Update Optimization
+```csharp
+public class OptimizedUpdater : MonoBehaviour
+{
+    private static readonly List<IUpdatable> updatables = new();
+    private static readonly List<IFixedUpdatable> fixedUpdatables = new();
+
+    public static void Register(IUpdatable updatable) => updatables.Add(updatable);
+    public static void Unregister(IUpdatable updatable) => updatables.Remove(updatable);
+
+    private void Update()
+    {
+        float deltaTime = Time.deltaTime;
+        for (int i = 0; i < updatables.Count; i++)
+            updatables[i].OnUpdate(deltaTime);
+    }
+
+    private void FixedUpdate()
+    {
+        float fixedDeltaTime = Time.fixedDeltaTime;
+        for (int i = 0; i < fixedUpdatables.Count; i++)
+            fixedUpdatables[i].OnFixedUpdate(fixedDeltaTime);
+    }
+}
+
+public interface IUpdatable
+{
+    void OnUpdate(float deltaTime);
+}
+```
+
+### Memory Optimization
+```csharp
+// Avoid allocations in Update
+public class NoAllocExample : MonoBehaviour
+{
+    // Cache references
+    private Transform cachedTransform;
+    private Rigidbody cachedRigidbody;
+
+    // Pre-allocate arrays
+    private readonly Collider[] hitResults = new Collider[32];
+    private readonly RaycastHit[] rayResults = new RaycastHit[16];
+
+    // Use StringBuilder for strings
+    private readonly StringBuilder stringBuilder = new(256);
+
+    private void Awake()
+    {
+        cachedTransform = transform;
+        cachedRigidbody = GetComponent<Rigidbody>();
+    }
+
+    private void Update()
+    {
+        // Non-allocating physics
+        int hitCount = Physics.OverlapSphereNonAlloc(
+            cachedTransform.position, 5f, hitResults);
+
+        for (int i = 0; i < hitCount; i++)
+        {
+            ProcessHit(hitResults[i]);
+        }
+    }
+}
+```
+
+## Best Practices
+
+1. **Use ScriptableObjects**: Data-driven design
+2. **Pool Everything**: Reuse instantiated objects
+3. **Cache Components**: GetComponent is expensive
+4. **Avoid Update**: Use events when possible
+5. **Profile Regularly**: Use Unity Profiler
+
+## Anti-Patterns
+
+- Singleton overuse
+- Find/GetComponent in Update
+- String comparisons for tags
+- Allocations in hot paths
+- Deep inheritance hierarchies
+
+## When to Use
+
+- Any Unity game project
+- Team collaboration needed
+- Performance-critical games
+- Data-driven game design
+- Scalable architecture
+
+## When NOT to Use
+
+- Very simple prototypes
+- Game jams (may be overkill)
+- Learning Unity basics