@djm204/agent-skills 1.0.0

package/templates/engineering/unity-dev-expert/.cursor/rules/csharp-architecture.mdc

@@ -0,0 +1,61 @@
+---
+description: C# Architecture
+alwaysApply: false
+---
+
+# C# Architecture
+
+Guidelines for C# scripting patterns, MonoBehaviour lifecycle, and testable code in Unity.
+
+## Core Principles
+
+- Prefer composition over inheritance for game object behaviour
+- Keep MonoBehaviours thin; delegate logic to plain C# classes
+- Use ScriptableObjects for shared data and event channels
+- Favour async/await (UniTask) over coroutines for complex flows
+- Design for testability: inject dependencies, avoid static singletons
+
+## Lifecycle Method Usage
+
+| Method | Use For | Avoid |
+|--------|---------|-------|
+| Awake | Cache component refs, self-init | Accessing other objects |
+| OnEnable | Subscribe to events | Heavy computation |
+| Start | Cross-object init | Anything needed by another Awake |
+| Update | Per-frame game logic | Physics, heavy allocations |
+| FixedUpdate | Physics forces, raycasts | Camera movement, input |
+| LateUpdate | Camera follow | Physics manipulation |
+| OnDisable | Unsubscribe events | Accessing destroyed objects |
+
+## ScriptableObject Patterns
+
+| Pattern | Purpose |
+|---------|---------|
+| Data Container | Decouple config from behaviour (WeaponData, EnemyConfig) |
+| Event Channel | Decouple publishers/subscribers (OnPlayerDied) |
+| Runtime Set | Track active instances without FindObjectsOfType |
+| Enum Replacement | Extensible type-safe categories (DamageType) |
+
+## Async: Coroutines vs UniTask
+
+| Feature | Coroutines | UniTask |
+|---------|------------|---------|
+| Cancellation | StopCoroutine (fragile) | CancellationToken (robust) |
+| Return values | Not supported | Full Task<T> support |
+| Error handling | Silently swallowed | try/catch |
+| GC allocation | IEnumerator allocates | Zero-alloc |
+
+## Testable Code
+
+- **Thin MonoBehaviours**: Cache refs, forward input, apply results, manage lifecycle
+- **Pure C# classes**: State machines, damage calc, inventory logic, pathfinding
+- **Edit Mode tests**: NUnit + Unity Test Framework for pure C#, ScriptableObjects
+- **Play Mode tests**: Unity Test Framework for component interactions, scenes
+
+## Common Pitfalls
+
+**Deep Inheritance**: `BossEnemy : RangedEnemy : BaseEnemy` with 5 levels of overrides. Compose small components instead: Health, Attack, Movement.
+
+**Singletons Everywhere**: Hidden dependencies, untestable code. Use a service locator or DI; pass deps explicitly.
+
+**Not Caching GetComponent**: Calling `GetComponent<Rigidbody>()` every frame. Cache in Awake.

package/templates/engineering/unity-dev-expert/.cursor/rules/multiplayer-networking.mdc

@@ -0,0 +1,67 @@
+---
+description: Multiplayer and Networking
+alwaysApply: false
+---
+
+# Multiplayer and Networking
+
+Guidelines for building multiplayer games with Netcode for GameObjects.
+
+## Core Principles
+
+- Server is authoritative for all gameplay state; never trust the client
+- Synchronize only gameplay state, not visual effects
+- Design for latency from day one; add prediction and interpolation early
+- Test with simulated latency and packet loss, not just localhost
+
+## Data Flow
+
+- Client sends input via **ServerRpc**
+- Server validates, simulates, updates **NetworkVariables**
+- Clients receive state, reconcile predictions, interpolate remote entities
+
+## RPC and Sync Guidelines
+
+| Type | Direction | Use For |
+|------|-----------|---------|
+| ServerRpc | Client -> Server | Player input, action requests |
+| ClientRpc | Server -> Client(s) | VFX triggers, audio cues |
+| NetworkVariable | Server -> All | Gameplay state (health, position) |
+
+**Sync**: Position, health, score, equipped item, match timer
+**Don't sync**: Particles, animation blends, footsteps, camera shake, UI animations
+
+## Lag Compensation
+
+| Technique | Purpose |
+|-----------|---------|
+| Client-side prediction | Responsive local movement; apply input immediately |
+| Server reconciliation | Correct prediction errors from last confirmed state |
+| Entity interpolation | Smooth remote entities; buffer 2-3 states |
+| Lag compensation | Fair hit detection; rewind server to client view time |
+
+## Network Testing
+
+| Condition | Simulate | Expected |
+|-----------|----------|----------|
+| 50ms RTT | Typical broadband | Smooth with prediction |
+| 150ms RTT | Mobile / cross-region | Noticeable but playable |
+| 5% packet loss | Unstable WiFi | Interpolation hides gaps |
+
+Use Unity Transport simulator or Clumsy/NetEm.
+
+## Security
+
+| Threat | Mitigation |
+|--------|-----------|
+| Speed hacking | Server validates movement delta per tick |
+| Packet injection | Validate all ServerRpc params on server |
+| State spoofing | Only server writes NetworkVariables |
+
+## Common Pitfalls
+
+**Trusting Client State**: Client sends `TakeDamageServerRpc(999)` and server applies directly. Server must calculate damage from weapon data and hit validation.
+
+**Syncing Visual Data**: NetworkVariable for particle colors and animation params. Sync gameplay state; derive visuals locally.
+
+**No Prediction on Owned Objects**: Waiting for server confirmation before moving local player. Apply input immediately, reconcile on server state arrival.

package/templates/engineering/unity-dev-expert/.cursor/rules/overview.mdc

@@ -0,0 +1,56 @@
+---
+description: Unity Dev Expert Overview
+alwaysApply: false
+---
+
+# Unity Dev Expert Overview
+
+Principal-level guidelines for Unity game development covering architecture, performance, and cross-platform delivery.
+
+## Scope
+
+- C# scripting architecture and MonoBehaviour lifecycle
+- ECS/DOTS for high-performance scenarios
+- Physics simulation, collision detection, raycasting
+- Shader programming (Shader Graph, HLSL, URP, HDRP)
+- UI development (UI Toolkit, UGUI)
+- Multiplayer networking (Netcode for GameObjects)
+- Performance profiling, memory management, optimization
+- Asset pipeline, Addressables, platform builds
+
+## Core Principles
+
+- **Composition Over Inheritance**: MonoBehaviours are components, not base classes. Combine small, focused components.
+- **Data-Oriented Mindset**: Think data layout, cache coherence, batch processing. ECS/DOTS formalizes this.
+- **Profile Before Optimizing**: Use Unity Profiler on target device. Never guess bottlenecks.
+- **Deterministic Lifecycle**: Know Awake/OnEnable/Start/Update/FixedUpdate/LateUpdate order. Init-order bugs are common.
+- **Platform-Aware Design**: Frame budgets, input, memory, and rendering vary across mobile/console/VR/desktop.
+- **Testable Architecture**: Separate logic from MonoBehaviour. Keep pure C# testable outside the engine.
+
+## When to Use ECS vs MonoBehaviour
+
+| Criteria | MonoBehaviour | ECS/DOTS |
+|----------|---------------|----------|
+| Entity count | <1,000 | 1,000-1,000,000+ |
+| Team familiarity | Standard Unity | Requires DOTS training |
+| Iteration speed | Fast prototyping | Slower initial setup |
+| Performance ceiling | Moderate | Very high (Burst + Jobs) |
+| Third-party assets | Full support | Limited |
+
+## Key Technology Choices
+
+| System | Primary | When to Consider Alternatives |
+|--------|---------|-------------------------------|
+| Input | Input System Package | Never use legacy Input |
+| Asset Loading | Addressables | Avoid Resources.Load |
+| UI | UI Toolkit (new) / UGUI (VR/world-space) | IMGUI for debug only |
+| Networking | Netcode for GameObjects | Mirror/Photon for specific needs |
+| Rendering | URP (most) / HDRP (high-end PC/console) | Built-in for legacy only |
+
+## Common Pitfalls
+
+**GC Allocations in Hot Paths**: Strings, LINQ, arrays in Update. Cache allocations, use StringBuilder.
+
+**Ignoring Execution Order**: Assuming Start runs before another Awake. Use Script Execution Order or explicit init chains.
+
+**Over-Networking**: Syncing particles and animations. Sync authoritative gameplay state; derive visuals locally.

package/templates/engineering/unity-dev-expert/.cursor/rules/performance-optimization.mdc

@@ -0,0 +1,76 @@
+---
+description: Performance and Optimization
+alwaysApply: false
+---
+
+# Performance and Optimization
+
+Guidelines for profiling, memory management, draw call reduction, and platform tuning in Unity.
+
+## Core Principles
+
+- Profile on the target device, not the Editor
+- Fix the biggest bottleneck first; don't scatter-shot optimize
+- Set explicit frame budgets per platform before development
+- Measure before and after every optimization
+
+## Frame Budgets
+
+| Platform | FPS | Budget | Max Draw Calls | Max Tris |
+|----------|-----|--------|----------------|----------|
+| Mobile (low) | 30 | 33.3ms | <100 | <100K |
+| Mobile (high) | 60 | 16.6ms | <200 | <300K |
+| Console | 60 | 16.6ms | <2,000 | <2M |
+| VR (Quest) | 72 | 13.8ms | <100 | <150K |
+| VR (PCVR) | 90 | 11.1ms | <1,000 | <1M |
+
+## GC Allocation Hotspots
+
+| Source | Fix |
+|--------|-----|
+| String concat in Update | Use StringBuilder once |
+| LINQ in hot paths | Manual loops |
+| Boxing value types | Generic collections |
+| Lambda captures | Cache delegate |
+| FindObjectsOfType | Cache results, runtime sets |
+| foreach on non-List | for-loop or List<T> |
+
+## Draw Call Reduction
+
+| Technique | How |
+|-----------|-----|
+| SRP Batcher | Auto with URP/HDRP; batches by shader |
+| GPU Instancing | Same mesh + material in one call |
+| Static Batching | Combines static meshes at build time |
+| Texture Atlasing | Reduces material switches |
+
+## Memory Budgets
+
+| Platform | Budget | Texture Budget |
+|----------|--------|----------------|
+| Mobile (2GB) | <600MB | <200MB |
+| Mobile (4GB) | <1.2GB | <400MB |
+| Quest 2/3 | <1.5GB | <512MB |
+
+## Texture Formats
+
+- **iOS/Android (modern)**: ASTC 6x6
+- **Android (old)**: ETC2 fallback
+- **PC/Console**: BC7
+
+## Platform-Specific Settings
+
+| Platform | Critical Settings |
+|----------|------------------|
+| iOS | Metal API, ASTC textures, IL2CPP |
+| Android | Vulkan primary, GLES 3.2 fallback |
+| Quest VR | Single-pass instanced, fixed foveated rendering |
+| WebGL | Code stripping, compressed textures, no threads |
+
+## Common Pitfalls
+
+**Editor-Only Profiling**: Editor overhead distorts results. Deploy dev builds to target device, connect Profiler via USB/IP.
+
+**Premature Optimization**: Writing Burst jobs for menu screens. Identify actual bottlenecks via Profiler first.
+
+**GC in Hot Loops**: LINQ, string concat, or `new List<T>()` inside Update/FixedUpdate. Pre-allocate everything.

package/templates/engineering/unity-dev-expert/.cursor/rules/physics-rendering.mdc

@@ -0,0 +1,59 @@
+---
+description: Physics and Rendering
+alwaysApply: false
+---
+
+# Physics and Rendering
+
+Guidelines for physics systems, collision management, render pipelines, and shaders in Unity.
+
+## Core Principles
+
+- Use physics for physics, not gameplay triggers (prefer overlap queries)
+- Always set collision layers and layer masks to avoid unnecessary checks
+- Select the render pipeline at project start; switching later is costly
+- Profile GPU on target hardware, not in the Editor
+
+## Physics System Selection
+
+| Need | Recommended | Notes |
+|------|-------------|-------|
+| Player movement (arcade) | CharacterController | Built-in slopes, steps |
+| Player movement (realistic) | Rigidbody + capsule | Responds to forces |
+| Hitscan weapons | Physics.Raycast | Instant, use NonAlloc |
+| Slow projectiles | Rigidbody + collider | Gravity, bounce for free |
+| Fast projectiles | Raycast per frame | Prevents tunneling |
+| Area detection | OverlapSphere/Box | No rigidbody needed |
+
+## Render Pipeline Comparison
+
+| Feature | URP | HDRP | Built-in |
+|---------|-----|------|----------|
+| Targets | All platforms | PC, Console | Legacy only |
+| SRP Batcher | Yes | Yes | No |
+| Ray tracing | Limited | Full | No |
+| Custom passes | RenderFeature | CustomPass | CommandBuffer |
+
+## Lighting Strategy
+
+- **Static light?** Baked lightmaps (best performance)
+- **Dynamic, few objects?** Realtime point/spot (limit range)
+- **Dynamic, many objects?** Mixed lighting (bake indirect, realtime direct)
+- **VR**: Baked strongly preferred; realtime shadows expensive at 90 FPS
+
+## LOD Guidelines
+
+| Level | Screen % | Detail |
+|-------|----------|--------|
+| LOD0 | 0-15% | Full mesh, all VFX |
+| LOD1 | 15-30% | 50% polys, simplified VFX |
+| LOD2 | 30-60% | 25% polys, no VFX |
+| Culled | >60% | Not rendered |
+
+## Common Pitfalls
+
+**Moving Static Colliders**: Moving a collider without a Rigidbody rebuilds the collision tree every frame. Add Kinematic Rigidbody to moving colliders.
+
+**Mesh Colliders on Dynamic Objects**: Expensive and limited. Approximate with box/sphere/capsule compound colliders.
+
+**No Layer Masks on Raycasts**: `Physics.Raycast(ray, out hit, 100f)` checks everything. Always pass a layer mask.

package/templates/engineering/unity-dev-expert/.cursor/rules/ui-systems.mdc

@@ -0,0 +1,59 @@
+---
+description: UI Systems
+alwaysApply: false
+---
+
+# UI Systems
+
+Guidelines for building runtime user interfaces in Unity using UI Toolkit and UGUI.
+
+## Core Principles
+
+- Separate UI logic (presenter) from layout (view) and game state (model)
+- UI Toolkit for new projects with complex layouts; UGUI for world-space and VR
+- Design responsive layouts for different screen sizes and safe areas
+- Minimize Canvas rebuilds (UGUI) and USS recalculations (UI Toolkit)
+
+## System Selection
+
+| Criteria | UI Toolkit | UGUI |
+|----------|-----------|------|
+| New runtime UI | Preferred | Acceptable |
+| World-space / VR | Limited | Preferred |
+| Data binding | Built-in | Manual |
+| Layout system | Flexbox (USS) | RectTransform anchors |
+| Editor extensions | Primary choice | Legacy |
+
+## MVP Architecture
+
+- **Model** (ScriptableObject / C#): Game state data, raises change events, no UI refs
+- **Presenter** (MonoBehaviour): Queries view in OnEnable, subscribes to model, forwards input
+- **View** (UXML+USS / Canvas): Pure layout and style, no game logic
+
+## UGUI Performance
+
+| Problem | Solution |
+|---------|----------|
+| Canvas rebuild spikes | Split static/dynamic into sub-canvases |
+| Nested LayoutGroup stutter | Avoid nesting > 2 levels |
+| Overdraw on mobile | Reduce layers, sprite packing |
+| Raycast on everything | Disable Raycast Target on non-interactive elements |
+
+Rule: Elements that change together share a Canvas. Different update rates get separate Canvases.
+
+## Responsive Design
+
+| Platform | Strategy | Key Consideration |
+|----------|----------|-------------------|
+| Mobile | Flex column | Touch target min 44x44 dp |
+| Desktop | Fixed or scaled | Mouse hover states |
+| Console TV | Overscan safe area | Large text, 10-foot UI |
+| VR | World-space 2-3m | No small text, gaze targets |
+
+## Common Pitfalls
+
+**Querying Elements Every Frame**: Calling `root.Q<Label>("score")` in Update. Cache the reference in OnEnable.
+
+**Ignoring Raycast Target**: Leaving it enabled on all Images and Text. Disable on non-interactive elements.
+
+**Hardcoded Pixel Sizes**: Use USS relative units, CanvasScaler with reference resolution, or DPI scaling.