@ruaruababa/vibe-kit 1.0.0

package/skills/unity-ecs-patterns/resources/implementation-playbook.md

@@ -0,0 +1,625 @@
+# Unity ECS Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# Unity ECS Patterns
+
+Production patterns for Unity's Data-Oriented Technology Stack (DOTS) including Entity Component System, Job System, and Burst Compiler.
+
+## When to Use This Skill
+
+- Building high-performance Unity games
+- Managing thousands of entities efficiently
+- Implementing data-oriented game systems
+- Optimizing CPU-bound game logic
+- Converting OOP game code to ECS
+- Using Jobs and Burst for parallelization
+
+## Core Concepts
+
+### 1. ECS vs OOP
+
+| Aspect | Traditional OOP | ECS/DOTS |
+|--------|-----------------|----------|
+| Data layout | Object-oriented | Data-oriented |
+| Memory | Scattered | Contiguous |
+| Processing | Per-object | Batched |
+| Scaling | Poor with count | Linear scaling |
+| Best for | Complex behaviors | Mass simulation |
+
+### 2. DOTS Components
+
+```
+Entity: Lightweight ID (no data)
+Component: Pure data (no behavior)
+System: Logic that processes components
+World: Container for entities
+Archetype: Unique combination of components
+Chunk: Memory block for same-archetype entities
+```
+
+## Patterns
+
+### Pattern 1: Basic ECS Setup
+
+```csharp
+using Unity.Entities;
+using Unity.Mathematics;
+using Unity.Transforms;
+using Unity.Burst;
+using Unity.Collections;
+
+// Component: Pure data, no methods
+public struct Speed : IComponentData
+{
+    public float Value;
+}
+
+public struct Health : IComponentData
+{
+    public float Current;
+    public float Max;
+}
+
+public struct Target : IComponentData
+{
+    public Entity Value;
+}
+
+// Tag component (zero-size marker)
+public struct EnemyTag : IComponentData { }
+public struct PlayerTag : IComponentData { }
+
+// Buffer component (variable-size array)
+[InternalBufferCapacity(8)]
+public struct InventoryItem : IBufferElementData
+{
+    public int ItemId;
+    public int Quantity;
+}
+
+// Shared component (grouped entities)
+public struct TeamId : ISharedComponentData
+{
+    public int Value;
+}
+```
+
+### Pattern 2: Systems with ISystem (Recommended)
+
+```csharp
+using Unity.Entities;
+using Unity.Transforms;
+using Unity.Mathematics;
+using Unity.Burst;
+
+// ISystem: Unmanaged, Burst-compatible, highest performance
+[BurstCompile]
+public partial struct MovementSystem : ISystem
+{
+    [BurstCompile]
+    public void OnCreate(ref SystemState state)
+    {
+        // Require components before system runs
+        state.RequireForUpdate<Speed>();
+    }
+
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        float deltaTime = SystemAPI.Time.DeltaTime;
+
+        // Simple foreach - auto-generates job
+        foreach (var (transform, speed) in
+            SystemAPI.Query<RefRW<LocalTransform>, RefRO<Speed>>())
+        {
+            transform.ValueRW.Position +=
+                new float3(0, 0, speed.ValueRO.Value * deltaTime);
+        }
+    }
+
+    [BurstCompile]
+    public void OnDestroy(ref SystemState state) { }
+}
+
+// With explicit job for more control
+[BurstCompile]
+public partial struct MovementJobSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        var job = new MoveJob
+        {
+            DeltaTime = SystemAPI.Time.DeltaTime
+        };
+
+        state.Dependency = job.ScheduleParallel(state.Dependency);
+    }
+}
+
+[BurstCompile]
+public partial struct MoveJob : IJobEntity
+{
+    public float DeltaTime;
+
+    void Execute(ref LocalTransform transform, in Speed speed)
+    {
+        transform.Position += new float3(0, 0, speed.Value * DeltaTime);
+    }
+}
+```
+
+### Pattern 3: Entity Queries
+
+```csharp
+[BurstCompile]
+public partial struct QueryExamplesSystem : ISystem
+{
+    private EntityQuery _enemyQuery;
+
+    public void OnCreate(ref SystemState state)
+    {
+        // Build query manually for complex cases
+        _enemyQuery = new EntityQueryBuilder(Allocator.Temp)
+            .WithAll<EnemyTag, Health, LocalTransform>()
+            .WithNone<Dead>()
+            .WithOptions(EntityQueryOptions.FilterWriteGroup)
+            .Build(ref state);
+    }
+
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        // SystemAPI.Query - simplest approach
+        foreach (var (health, entity) in
+            SystemAPI.Query<RefRW<Health>>()
+                .WithAll<EnemyTag>()
+                .WithEntityAccess())
+        {
+            if (health.ValueRO.Current <= 0)
+            {
+                // Mark for destruction
+                SystemAPI.GetSingleton<EndSimulationEntityCommandBufferSystem.Singleton>()
+                    .CreateCommandBuffer(state.WorldUnmanaged)
+                    .DestroyEntity(entity);
+            }
+        }
+
+        // Get count
+        int enemyCount = _enemyQuery.CalculateEntityCount();
+
+        // Get all entities
+        var enemies = _enemyQuery.ToEntityArray(Allocator.Temp);
+
+        // Get component arrays
+        var healths = _enemyQuery.ToComponentDataArray<Health>(Allocator.Temp);
+    }
+}
+```
+
+### Pattern 4: Entity Command Buffers (Structural Changes)
+
+```csharp
+// Structural changes (create/destroy/add/remove) require command buffers
+[BurstCompile]
+[UpdateInGroup(typeof(SimulationSystemGroup))]
+public partial struct SpawnSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        var ecbSingleton = SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>();
+        var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);
+
+        foreach (var (spawner, transform) in
+            SystemAPI.Query<RefRW<Spawner>, RefRO<LocalTransform>>())
+        {
+            spawner.ValueRW.Timer -= SystemAPI.Time.DeltaTime;
+
+            if (spawner.ValueRO.Timer <= 0)
+            {
+                spawner.ValueRW.Timer = spawner.ValueRO.Interval;
+
+                // Create entity (deferred until sync point)
+                Entity newEntity = ecb.Instantiate(spawner.ValueRO.Prefab);
+
+                // Set component values
+                ecb.SetComponent(newEntity, new LocalTransform
+                {
+                    Position = transform.ValueRO.Position,
+                    Rotation = quaternion.identity,
+                    Scale = 1f
+                });
+
+                // Add component
+                ecb.AddComponent(newEntity, new Speed { Value = 5f });
+            }
+        }
+    }
+}
+
+// Parallel ECB usage
+[BurstCompile]
+public partial struct ParallelSpawnJob : IJobEntity
+{
+    public EntityCommandBuffer.ParallelWriter ECB;
+
+    void Execute([EntityIndexInQuery] int index, in Spawner spawner)
+    {
+        Entity e = ECB.Instantiate(index, spawner.Prefab);
+        ECB.AddComponent(index, e, new Speed { Value = 5f });
+    }
+}
+```
+
+### Pattern 5: Aspect (Grouping Components)
+
+```csharp
+using Unity.Entities;
+using Unity.Transforms;
+using Unity.Mathematics;
+
+// Aspect: Groups related components for cleaner code
+public readonly partial struct CharacterAspect : IAspect
+{
+    public readonly Entity Entity;
+
+    private readonly RefRW<LocalTransform> _transform;
+    private readonly RefRO<Speed> _speed;
+    private readonly RefRW<Health> _health;
+
+    // Optional component
+    [Optional]
+    private readonly RefRO<Shield> _shield;
+
+    // Buffer
+    private readonly DynamicBuffer<InventoryItem> _inventory;
+
+    public float3 Position
+    {
+        get => _transform.ValueRO.Position;
+        set => _transform.ValueRW.Position = value;
+    }
+
+    public float CurrentHealth => _health.ValueRO.Current;
+    public float MaxHealth => _health.ValueRO.Max;
+    public float MoveSpeed => _speed.ValueRO.Value;
+
+    public bool HasShield => _shield.IsValid;
+    public float ShieldAmount => HasShield ? _shield.ValueRO.Amount : 0f;
+
+    public void TakeDamage(float amount)
+    {
+        float remaining = amount;
+
+        if (HasShield && _shield.ValueRO.Amount > 0)
+        {
+            // Shield absorbs damage first
+            remaining = math.max(0, amount - _shield.ValueRO.Amount);
+        }
+
+        _health.ValueRW.Current = math.max(0, _health.ValueRO.Current - remaining);
+    }
+
+    public void Move(float3 direction, float deltaTime)
+    {
+        _transform.ValueRW.Position += direction * _speed.ValueRO.Value * deltaTime;
+    }
+
+    public void AddItem(int itemId, int quantity)
+    {
+        _inventory.Add(new InventoryItem { ItemId = itemId, Quantity = quantity });
+    }
+}
+
+// Using aspect in system
+[BurstCompile]
+public partial struct CharacterSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        float dt = SystemAPI.Time.DeltaTime;
+
+        foreach (var character in SystemAPI.Query<CharacterAspect>())
+        {
+            character.Move(new float3(1, 0, 0), dt);
+
+            if (character.CurrentHealth < character.MaxHealth * 0.5f)
+            {
+                // Low health logic
+            }
+        }
+    }
+}
+```
+
+### Pattern 6: Singleton Components
+
+```csharp
+// Singleton: Exactly one entity with this component
+public struct GameConfig : IComponentData
+{
+    public float DifficultyMultiplier;
+    public int MaxEnemies;
+    public float SpawnRate;
+}
+
+public struct GameState : IComponentData
+{
+    public int Score;
+    public int Wave;
+    public float TimeRemaining;
+}
+
+// Create singleton on world creation
+public partial struct GameInitSystem : ISystem
+{
+    public void OnCreate(ref SystemState state)
+    {
+        var entity = state.EntityManager.CreateEntity();
+        state.EntityManager.AddComponentData(entity, new GameConfig
+        {
+            DifficultyMultiplier = 1.0f,
+            MaxEnemies = 100,
+            SpawnRate = 2.0f
+        });
+        state.EntityManager.AddComponentData(entity, new GameState
+        {
+            Score = 0,
+            Wave = 1,
+            TimeRemaining = 120f
+        });
+    }
+}
+
+// Access singleton in system
+[BurstCompile]
+public partial struct ScoreSystem : ISystem
+{
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        // Read singleton
+        var config = SystemAPI.GetSingleton<GameConfig>();
+
+        // Write singleton
+        ref var gameState = ref SystemAPI.GetSingletonRW<GameState>().ValueRW;
+        gameState.TimeRemaining -= SystemAPI.Time.DeltaTime;
+
+        // Check exists
+        if (SystemAPI.HasSingleton<GameConfig>())
+        {
+            // ...
+        }
+    }
+}
+```
+
+### Pattern 7: Baking (Converting GameObjects)
+
+```csharp
+using Unity.Entities;
+using UnityEngine;
+
+// Authoring component (MonoBehaviour in Editor)
+public class EnemyAuthoring : MonoBehaviour
+{
+    public float Speed = 5f;
+    public float Health = 100f;
+    public GameObject ProjectilePrefab;
+
+    class Baker : Baker<EnemyAuthoring>
+    {
+        public override void Bake(EnemyAuthoring authoring)
+        {
+            var entity = GetEntity(TransformUsageFlags.Dynamic);
+
+            AddComponent(entity, new Speed { Value = authoring.Speed });
+            AddComponent(entity, new Health
+            {
+                Current = authoring.Health,
+                Max = authoring.Health
+            });
+            AddComponent(entity, new EnemyTag());
+
+            if (authoring.ProjectilePrefab != null)
+            {
+                AddComponent(entity, new ProjectilePrefab
+                {
+                    Value = GetEntity(authoring.ProjectilePrefab, TransformUsageFlags.Dynamic)
+                });
+            }
+        }
+    }
+}
+
+// Complex baking with dependencies
+public class SpawnerAuthoring : MonoBehaviour
+{
+    public GameObject[] Prefabs;
+    public float Interval = 1f;
+
+    class Baker : Baker<SpawnerAuthoring>
+    {
+        public override void Bake(SpawnerAuthoring authoring)
+        {
+            var entity = GetEntity(TransformUsageFlags.Dynamic);
+
+            AddComponent(entity, new Spawner
+            {
+                Interval = authoring.Interval,
+                Timer = 0f
+            });
+
+            // Bake buffer of prefabs
+            var buffer = AddBuffer<SpawnPrefabElement>(entity);
+            foreach (var prefab in authoring.Prefabs)
+            {
+                buffer.Add(new SpawnPrefabElement
+                {
+                    Prefab = GetEntity(prefab, TransformUsageFlags.Dynamic)
+                });
+            }
+
+            // Declare dependencies
+            DependsOn(authoring.Prefabs);
+        }
+    }
+}
+```
+
+### Pattern 8: Jobs with Native Collections
+
+```csharp
+using Unity.Jobs;
+using Unity.Collections;
+using Unity.Burst;
+using Unity.Mathematics;
+
+[BurstCompile]
+public struct SpatialHashJob : IJobParallelFor
+{
+    [ReadOnly]
+    public NativeArray<float3> Positions;
+
+    // Thread-safe write to hash map
+    public NativeParallelMultiHashMap<int, int>.ParallelWriter HashMap;
+
+    public float CellSize;
+
+    public void Execute(int index)
+    {
+        float3 pos = Positions[index];
+        int hash = GetHash(pos);
+        HashMap.Add(hash, index);
+    }
+
+    int GetHash(float3 pos)
+    {
+        int x = (int)math.floor(pos.x / CellSize);
+        int y = (int)math.floor(pos.y / CellSize);
+        int z = (int)math.floor(pos.z / CellSize);
+        return x * 73856093 ^ y * 19349663 ^ z * 83492791;
+    }
+}
+
+[BurstCompile]
+public partial struct SpatialHashSystem : ISystem
+{
+    private NativeParallelMultiHashMap<int, int> _hashMap;
+
+    public void OnCreate(ref SystemState state)
+    {
+        _hashMap = new NativeParallelMultiHashMap<int, int>(10000, Allocator.Persistent);
+    }
+
+    public void OnDestroy(ref SystemState state)
+    {
+        _hashMap.Dispose();
+    }
+
+    [BurstCompile]
+    public void OnUpdate(ref SystemState state)
+    {
+        var query = SystemAPI.QueryBuilder()
+            .WithAll<LocalTransform>()
+            .Build();
+
+        int count = query.CalculateEntityCount();
+
+        // Resize if needed
+        if (_hashMap.Capacity < count)
+        {
+            _hashMap.Capacity = count * 2;
+        }
+
+        _hashMap.Clear();
+
+        // Get positions
+        var positions = query.ToComponentDataArray<LocalTransform>(Allocator.TempJob);
+        var posFloat3 = new NativeArray<float3>(count, Allocator.TempJob);
+
+        for (int i = 0; i < count; i++)
+        {
+            posFloat3[i] = positions[i].Position;
+        }
+
+        // Build hash map
+        var hashJob = new SpatialHashJob
+        {
+            Positions = posFloat3,
+            HashMap = _hashMap.AsParallelWriter(),
+            CellSize = 10f
+        };
+
+        state.Dependency = hashJob.Schedule(count, 64, state.Dependency);
+
+        // Cleanup
+        positions.Dispose(state.Dependency);
+        posFloat3.Dispose(state.Dependency);
+    }
+}
+```
+
+## Performance Tips
+
+```csharp
+// 1. Use Burst everywhere
+[BurstCompile]
+public partial struct MySystem : ISystem { }
+
+// 2. Prefer IJobEntity over manual iteration
+[BurstCompile]
+partial struct OptimizedJob : IJobEntity
+{
+    void Execute(ref LocalTransform transform) { }
+}
+
+// 3. Schedule parallel when possible
+state.Dependency = job.ScheduleParallel(state.Dependency);
+
+// 4. Use ScheduleParallel with chunk iteration
+[BurstCompile]
+partial struct ChunkJob : IJobChunk
+{
+    public ComponentTypeHandle<Health> HealthHandle;
+
+    public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex,
+        bool useEnabledMask, in v128 chunkEnabledMask)
+    {
+        var healths = chunk.GetNativeArray(ref HealthHandle);
+        for (int i = 0; i < chunk.Count; i++)
+        {
+            // Process
+        }
+    }
+}
+
+// 5. Avoid structural changes in hot paths
+// Use enableable components instead of add/remove
+public struct Disabled : IComponentData, IEnableableComponent { }
+```
+
+## Best Practices
+
+### Do's
+- **Use ISystem over SystemBase** - Better performance
+- **Burst compile everything** - Massive speedup
+- **Batch structural changes** - Use ECB
+- **Profile with Profiler** - Identify bottlenecks
+- **Use Aspects** - Clean component grouping
+
+### Don'ts
+- **Don't use managed types** - Breaks Burst
+- **Don't structural change in jobs** - Use ECB
+- **Don't over-architect** - Start simple
+- **Don't ignore chunk utilization** - Group similar entities
+- **Don't forget disposal** - Native collections leak
+
+## Resources
+
+- [Unity DOTS Documentation](https://docs.unity3d.com/Packages/com.unity.entities@latest)
+- [Unity DOTS Samples](https://github.com/Unity-Technologies/EntityComponentSystemSamples)
+- [Burst User Guide](https://docs.unity3d.com/Packages/com.unity.burst@latest)

package/skills/uv-package-manager/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: uv-package-manager
+description: Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.
+---
+
+# UV Package Manager
+
+Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.
+
+## Use this skill when
+
+- Setting up new Python projects quickly
+- Managing Python dependencies faster than pip
+- Creating and managing virtual environments
+- Installing Python interpreters
+- Resolving dependency conflicts efficiently
+- Migrating from pip/pip-tools/poetry
+- Speeding up CI/CD pipelines
+- Managing monorepo Python projects
+- Working with lockfiles for reproducible builds
+- Optimizing Docker builds with Python dependencies
+
+## Do not use this skill when
+
+- The task is unrelated to uv package manager
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.