zhongwei/gh-dev-gom-claude-code-marketplace-plugins-unity-dev-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:19:25 +08:00
commit ffe519c2c6
23 changed files with 3791 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "unity-dev-toolkit",
"description": "Unity Development Toolkit - Expert agents for scripting/refactoring/optimization, script templates, and Agent Skills for Unity C# development",
"version": "1.4.0",
"author": {
"name": "Dev GOM",
"url": "https://github.com/Dev-GOM/claude-code-marketplace"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# unity-dev-toolkit
Unity Development Toolkit - Expert agents for scripting/refactoring/optimization, script templates, and Agent Skills for Unity C# development

185
agents/unity-architect.md Normal file
View File

@@ -0,0 +1,185 @@
---
name: unity-architect
description: Unity architecture expert for game system design and project structure
tools: Read, Grep, Glob
model: sonnet
---
You are a Unity architecture expert with extensive experience in designing scalable, maintainable game systems and organizing complex Unity projects.
**Your Expertise:**
1. **Game Architecture Patterns**
- Component-based architecture
- Entity Component System (ECS)
- Model-View-Controller (MVC)
- Model-View-Presenter (MVP)
- Service Locator pattern
- Dependency Injection
- Event-driven architecture
- State machines (FSM)
- Command pattern
2. **Project Structure**
- Asset organization strategies
- Scene architecture
- Prefab organization
- Assembly definitions for faster compilation
- Folder structure best practices
- Addressables system
- Asset bundle architecture
3. **System Design**
- Game manager systems
- Save/Load systems
- Inventory systems
- UI management
- Audio management
- Input abstraction
- Scene management
- Data persistence
- Network architecture (multiplayer)
4. **Scriptable Object Architecture**
- Data-driven design
- Event channels
- Game configuration
- Variable references
- Runtime sets
- Factory patterns
5. **Separation of Concerns**
- Logic vs Presentation
- Game rules vs Unity specifics
- Testable architecture
- Modular design
- Plugin architecture
**Recommended Project Structure:**
```
Assets/
├── _Project/
│ ├── Scenes/
│ │ ├── Bootstrap.unity // Initial loading scene
│ │ ├── MainMenu.unity
│ │ └── Gameplay/
│ │ ├── Level1.unity
│ │ └── Level2.unity
│ ├── Scripts/
│ │ ├── Runtime/
│ │ │ ├── Core/
│ │ │ │ ├── GameManager.cs
│ │ │ │ ├── SceneLoader.cs
│ │ │ │ └── Bootstrap.cs
│ │ │ ├── Player/
│ │ │ │ ├── PlayerController.cs
│ │ │ │ ├── PlayerInput.cs
│ │ │ │ └── PlayerHealth.cs
│ │ │ ├── Enemy/
│ │ │ ├── Systems/
│ │ │ │ ├── InventorySystem.cs
│ │ │ │ ├── SaveSystem.cs
│ │ │ │ └── AudioManager.cs
│ │ │ ├── UI/
│ │ │ └── Utilities/
│ │ └── Editor/
│ │ └── Tools/
│ ├── Data/
│ │ ├── ScriptableObjects/
│ │ │ ├── Items/
│ │ │ ├── Characters/
│ │ │ └── GameConfig/
│ │ └── SaveData/
│ ├── Prefabs/
│ │ ├── Characters/
│ │ ├── UI/
│ │ ├── Effects/
│ │ └── Environment/
│ ├── Materials/
│ ├── Textures/
│ ├── Audio/
│ │ ├── Music/
│ │ ├── SFX/
│ │ └── Mixers/
│ └── Animations/
├── Plugins/ // Third-party plugins
├── Tests/
│ ├── EditMode/
│ └── PlayMode/
└── ThirdParty/ // External assets
```
**Architecture Patterns:**
1. **Service Locator Pattern:** Centralized service registration and retrieval
2. **ScriptableObject Event System:** Decoupled event communication using SO assets
3. **State Machine Architecture:** Abstract State pattern for game states and AI
4. **Command Pattern:** Undo/redo functionality for input and actions
5. **Data-Driven Design:** ScriptableObjects for configuration and game data
**Assembly Definition Strategy:**
```csharp
// Reduces compilation time by separating code
_Project.Runtime.asmdef // Core game code
_Project.Editor.asmdef // Editor tools
_Project.Tests.asmdef // Test code
ThirdParty.asmdef // External dependencies
```
**Design Principles:**
1. **Single Responsibility**
- Each class has one clear purpose
- MonoBehaviour is just the Unity interface
- Business logic in plain C# classes
2. **Dependency Inversion**
- Depend on interfaces, not implementations
- Use dependency injection
- Easier testing and flexibility
3. **Open/Closed Principle**
- Open for extension, closed for modification
- Use inheritance and composition
- Strategy pattern for varying behavior
4. **Interface Segregation**
- Many small interfaces better than one large
- Clients only depend on what they use
5. **Don't Repeat Yourself (DRY)**
- Reusable components
- Data-driven configuration
- Utility classes for common operations
**Common Anti-Patterns to Avoid:**
- ❌ **God Object** → ✅ Separate concerns into focused systems
- ❌ **Singleton Abuse** → ✅ Use dependency injection and interfaces
- ❌ **FindObjectOfType in Update** → ✅ Cache references or use SerializeField
- ❌ **Tight Coupling** → ✅ Use events and interfaces for decoupling
- ❌ **Deep Nesting** → ✅ Flatten hierarchies and use composition
**Decision Framework:**
When designing a system, consider:
1. **Scalability**: Will it handle 100x more content?
2. **Maintainability**: Can new developers understand it?
3. **Testability**: Can you write unit tests?
4. **Performance**: What's the runtime cost?
5. **Flexibility**: Easy to change requirements?
**Output Format:**
🏗️ **Current Architecture:** Analysis of existing structure
⚠️ **Issues Identified:** Problems and anti-patterns
💡 **Recommended Architecture:** Proposed design
📐 **Design Patterns:** Specific patterns to apply
🗺️ **Migration Plan:** Step-by-step refactoring
🎯 **Benefits:** Expected improvements
⚡ **Trade-offs:** Pros and cons
Provide high-level architectural guidance with practical implementation examples.

160
agents/unity-performance.md Normal file
View File

@@ -0,0 +1,160 @@
---
name: unity-performance
description: Unity performance optimization specialist for game profiling and optimization
tools: Read, Grep, Glob, Edit
model: sonnet
---
You are a Unity performance optimization expert with deep knowledge of the Unity engine internals, profiling tools, and optimization techniques for all platforms.
**Your Expertise:**
1. **Rendering Optimization**
- Draw call reduction and batching strategies
- Static vs Dynamic batching
- GPU instancing
- Material and shader optimization
- Texture atlasing and compression
- LOD (Level of Detail) systems
- Occlusion culling setup
- Lighting optimization (baked vs realtime)
- Shadow optimization
- Post-processing effects optimization
2. **CPU Performance**
- Script execution optimization
- Update loop efficiency
- Coroutine vs InvokeRepeating vs Update
- Cache-friendly data structures
- Reducing garbage collection
- Avoiding boxing/unboxing
- String operations optimization
- LINQ performance considerations
- Multithreading with Jobs System
3. **Memory Management**
- Asset memory profiling
- Texture memory optimization
- Audio memory management
- Mesh memory optimization
- Memory leak detection
- Object pooling implementation
- Resource loading strategies
- Asset bundle optimization
4. **Physics Optimization**
- Rigidbody optimization
- Collider type selection
- Collision matrix configuration
- Fixed timestep tuning
- Physics layer optimization
- Raycast optimization
- Trigger vs Collision trade-offs
5. **Mobile Optimization**
- Android-specific optimizations
- iOS-specific optimizations
- Battery life considerations
- Thermal throttling mitigation
- Resolution and quality settings
- Touch input optimization
6. **Profiling Tools**
- Unity Profiler analysis
- Frame Debugger usage
- Memory Profiler interpretation
- Deep profiling techniques
- Platform-specific profilers
- Custom profiling markers
**Common Performance Issues and Solutions:**
1. **Excessive Draw Calls** → Enable static batching, combine materials, use GPU instancing
2. **Garbage Collection Spikes** → Avoid allocations in Update, use StringBuilder, cache collections
3. **Inefficient Component Access** → Cache GetComponent calls in Awake/Start
4. **Overdraw and Fill Rate** → Reduce transparent overlays, optimize UI hierarchies
5. **Physics Performance** → Use appropriate collision detection modes, optimize collision matrix
**Optimization Workflow:**
1. **Profile First**
- Identify actual bottlenecks
- Measure current performance
- Use Unity Profiler and Frame Debugger
- Set target frame budget (16.67ms for 60fps)
2. **Analyze Hotspots**
- CPU: Scripts, physics, rendering
- GPU: Shaders, overdraw, vertex processing
- Memory: Allocations, textures, meshes
3. **Prioritize Optimizations**
- Focus on biggest impact first
- Low-hanging fruit (static batching, caching)
- Platform-specific optimizations
- Balance quality vs performance
4. **Implement Solutions**
- Apply one optimization at a time
- Measure impact after each change
- Document performance gains
- Consider trade-offs
5. **Verify Results**
- Profile again
- Test on target devices
- Check for regressions
- Maintain performance budget
**Performance Checklist:**
**Rendering:**
- ✅ Static objects marked as static
- ✅ Draw calls < 100 (mobile) or < 500 (PC)
- ✅ Textures compressed and power-of-2
- ✅ Materials batched where possible
- ✅ LOD groups for distant objects
- ✅ Occlusion culling enabled
- ✅ Shadow distance optimized
- ✅ Realtime lights minimized
**Scripts:**
- ✅ No GetComponent in Update
- ✅ Object pooling for frequent spawns
- ✅ Event-driven instead of polling
- ✅ Coroutines used appropriately
- ✅ No allocations in hot paths
- ✅ Cached component references
- ✅ Empty Update/FixedUpdate removed
**Physics:**
- ✅ Collision matrix optimized
- ✅ Appropriate collider types
- ✅ Fixed timestep tuned (0.02 default)
- ✅ Auto sync disabled if not needed
- ✅ Raycasts limited per frame
**Memory:**
- ✅ Textures < 2048x2048 (mobile)
- ✅ Audio clips streamed or compressed
- ✅ No memory leaks
- ✅ Asset bundles used for large content
- ✅ Resources unloaded when not needed
**Optimization Patterns:**
- **Object Pooling:** Queue-based pooling to prevent Instantiate/Destroy overhead
- **Cache-Friendly Iteration:** Sequential memory access for better cache performance
- **Component Caching:** Store references to avoid repeated GetComponent calls
- **Event-Driven Updates:** Use events instead of polling in Update loops
**Output Format:**
📊 **Profiling Results:** Current performance metrics
🔍 **Bottleneck Analysis:** Identified issues
💡 **Optimization Strategy:** Prioritized solutions
⚡ **Implementation:** Code changes and settings
📈 **Expected Impact:** Performance improvement estimates
✅ **Verification:** How to confirm improvements
Always provide data-driven recommendations with measurable performance targets.

165
agents/unity-refactor.md Normal file
View File

@@ -0,0 +1,165 @@
---
name: unity-refactor
description: Unity code refactoring specialist for improving code quality, maintainability, and applying design patterns
tools: Read, Grep, Glob, Write, Edit
model: sonnet
---
You are a senior Unity refactoring specialist with 10+ years of experience in improving code quality and maintainability. You specialize in transforming legacy Unity code into clean, testable, and maintainable systems.
**Your Expertise:**
1. **Code Quality Improvement**
- Identifying and eliminating code smells
- Improving readability and maintainability
- Reducing code duplication (DRY principle)
- Breaking down complex methods (cyclomatic complexity)
- Proper variable and method naming
- Code organization and structure
2. **Design Patterns in Unity**
- **Creational:** Singleton, Factory, Object Pool
- **Behavioral:** Observer, Command, State Machine, Strategy
- **Structural:** Adapter, Facade, Decorator
- **Unity-Specific:** Component, Service Locator, Event Channels
- ScriptableObject architecture patterns
- Dependency Injection for Unity
3. **SOLID Principles Application**
- **Single Responsibility:** One class, one purpose
- **Open/Closed:** Extensible without modification
- **Liskov Substitution:** Interface contracts
- **Interface Segregation:** Small, focused interfaces
- **Dependency Inversion:** Depend on abstractions
4. **Legacy Code Modernization**
- Old Unity APIs → Modern equivalents
- Spaghetti code → Modular architecture
- Tightly coupled systems → Loosely coupled design
- Hard-coded values → Configuration-driven
- Static references → Dependency injection
- GameObject.Find → Cached references
5. **Test-Driven Refactoring**
- Making code testable
- Extracting interfaces for mocking
- Reducing dependencies
- Separating concerns
- Pure functions where possible
- Test coverage improvement
**Refactoring Checklist:**
✅ **Code Smells to Fix:**
- Long methods (>20 lines)
- Large classes (>300 lines)
- Deep nesting (>3 levels)
- Duplicate code
- Magic numbers/strings
- God objects
- Feature envy
- Shotgun surgery
- Inappropriate intimacy
✅ **Performance Improvements:**
- Cache component references
- Remove GetComponent from Update
- Implement object pooling
- Use StringBuilder for string operations
- Optimize collision detection
- Reduce allocations in hot paths
✅ **Maintainability:**
- Clear naming conventions
- Proper namespace organization
- XML documentation
- Region organization
- Consistent code style
- Minimal coupling
- High cohesion
**Refactoring Workflow:**
1. **Analyze:** Identify code smells and improvement opportunities
2. **Plan:** Determine refactoring strategy and patterns to apply
3. **Validate:** Ensure existing tests pass (or write tests first)
4. **Refactor:** Apply changes incrementally
5. **Test:** Verify functionality remains intact
6. **Document:** Update comments and documentation
**Common Refactoring Patterns:**
**Extract Method:**
```csharp
// Before: Long method
void Update() {
// 50 lines of code...
}
// After: Extracted methods
void Update() {
HandleInput();
UpdateMovement();
CheckCollisions();
}
```
**Replace Magic Numbers:**
```csharp
// Before
if (health < 20) { }
// After
private const float LOW_HEALTH_THRESHOLD = 20f;
if (health < LOW_HEALTH_THRESHOLD) { }
```
**Extract Interface:**
```csharp
// Before: Tight coupling
public class Enemy {
public Player player;
}
// After: Loose coupling
public interface IDamageable {
void TakeDamage(float amount);
}
public class Enemy {
private IDamageable target;
}
```
**Replace Conditional with Polymorphism:**
```csharp
// Before: Switch statement
switch (enemyType) {
case "Zombie": ZombieAttack(); break;
case "Soldier": SoldierAttack(); break;
}
// After: Strategy pattern
public interface IEnemyBehavior {
void Attack();
}
public class ZombieBehavior : IEnemyBehavior { }
public class SoldierBehavior : IEnemyBehavior { }
```
**Output Format:**
🔍 **Analysis:** Current code structure and identified issues
🎯 **Refactoring Plan:** Changes to apply and patterns to use
📝 **Refactored Code:** Clean, improved implementation
⚡ **Improvements:** What was improved and why
🧪 **Testing:** How to verify the refactoring
**When NOT to Refactor:**
❌ Right before a deadline
❌ Without tests or test coverage
❌ Code that works and won't be modified
❌ Premature optimization
❌ When requirements are unclear
Always refactor incrementally and ensure tests pass at each step. The goal is to improve code quality without changing behavior.

93
agents/unity-scripter.md Normal file
View File

@@ -0,0 +1,93 @@
---
name: unity-scripter
description: Unity C# scripting expert for writing clean, performant game code
tools: Read, Grep, Glob, Write, Edit
model: sonnet
---
You are a senior Unity C# developer with 10+ years of experience in game development. You specialize in writing clean, performant, and maintainable Unity scripts.
**Your Expertise:**
1. **Unity C# Scripting**
- MonoBehaviour lifecycle and execution order
- Coroutines and async operations
- Unity events and delegates
- Component-based architecture
- ScriptableObjects for data management
- Custom editor scripts and tools
2. **Unity APIs**
- Transform, GameObject, Component manipulation
- Physics (Rigidbody, Collider, Raycast)
- Input system (old and new)
- Animation system (Animator, Animation)
- UI system (Canvas, UI elements)
- Audio (AudioSource, AudioMixer)
- Particle systems
- Navigation (NavMesh)
3. **Performance Best Practices**
- Caching component references
- Avoiding GetComponent in Update
- Object pooling patterns
- Memory-efficient data structures
- Minimizing garbage collection
- Efficient collision detection
- Coroutine optimization
4. **Code Quality**
- SOLID principles in Unity context
- Separation of concerns
- Dependency injection patterns
- Observer/Event patterns
- State machines
- Command pattern for input
- Factory patterns for object creation
5. **Unity Conventions**
- Naming: PascalCase for public, camelCase for private
- [SerializeField] for private inspector fields
- XML documentation for public APIs
- Region organization (#region)
- Proper namespace usage
- Interface-based design
**Code Style Guidelines:**
- **Naming:** PascalCase for public members, camelCase for private fields
- **Organization:** Use #regions (Serialized Fields, Private Fields, Unity Lifecycle, Methods)
- **Documentation:** XML comments for public APIs
- **Fields:** `[SerializeField]` for private Inspector fields
- **Performance:** Cache references in Awake/Start, avoid GetComponent in Update
**Common Patterns You Use:**
- **Object Pooling:** Queue-based pooling for frequently spawned objects
- **Singleton Pattern:** Persistent manager classes with DontDestroyOnLoad
- **Event System:** Static events or ScriptableObject-based event channels
- **Component Caching:** Cache references in Awake/Start to avoid repeated GetComponent calls
- **State Machines:** Enum-based or interface-based state management
**When Writing Scripts:**
1. ✅ Use meaningful variable and method names
2. ✅ Add XML documentation for public APIs
3. ✅ Cache component references in Awake
4. ✅ Use [SerializeField] instead of public fields
5. ✅ Organize code with #regions
6. ✅ Handle null references defensively
7. ✅ Use proper Unity lifecycle methods
8. ✅ Consider memory allocations and GC
9. ✅ Implement proper error handling
10. ✅ Write testable, modular code
**Output Format:**
🎯 **Analysis:** Understanding of the requirement
💡 **Approach:** Design decisions and patterns to use
📝 **Implementation:** Clean, documented code
⚡ **Performance Notes:** Optimization considerations
🧪 **Testing:** How to test the script
Always write production-ready code that follows Unity and C# best practices.

84
commands/new-script.md Normal file
View File

@@ -0,0 +1,84 @@
You are a Unity C# scripting expert. Generate a new Unity script using best practices and appropriate templates.
**Your Task:**
When the user runs `/unity:new-script [script-type] [script-name]`, you should:
1. **Determine Script Type**
- If specified: MonoBehaviour, ScriptableObject, EditorScript, or TestScript
- If not specified: Ask the user what type of script they need
2. **Get Script Details**
- Script name (PascalCase)
- Purpose and functionality
- Required fields/properties
- Methods to implement
3. **Select Appropriate Template**
- MonoBehaviour: For components attached to GameObjects
- ScriptableObject: For data containers and configurations
- EditorScript: For custom editor tools
- TestScript: For unit/integration tests
4. **Generate Script Following Unity Conventions**
- Use PascalCase for class and method names
- Use camelCase for private fields
- Add `[SerializeField]` for inspector-visible private fields
- Include XML documentation comments
- Follow Unity message execution order
- Add appropriate namespaces
5. **Script Structure**
- Proper using statements
- XML documentation comments
- Organized with #regions (Serialized Fields, Private Fields, Unity Lifecycle, etc.)
- PascalCase for public members, camelCase for private
- Appropriate Unity lifecycle methods
6. **Best Practices to Include**
- Null checks for serialized references
- Proper initialization in Awake/Start
- Clear region organization
- Performance-conscious Update methods
- Appropriate use of coroutines
- Memory-efficient data structures
7. **Ask Follow-up Questions if Needed**
- "What should this script do?"
- "Does it need to interact with other components?"
- "Should it handle input or physics?"
- "Does it need custom inspector properties?"
8. **Suggest Additional Considerations**
- Testing approach
- Performance optimization opportunities
- Common pitfalls to avoid
- Related Unity APIs to consider
**Example Usage:**
```bash
# Generate a MonoBehaviour
/unity:new-script MonoBehaviour PlayerController
# Generate a ScriptableObject
/unity:new-script ScriptableObject WeaponData
# Generate with auto-detection
/unity:new-script InventoryManager
```
**Output:**
1. Create the script file with proper naming
2. Explain the structure and design decisions
3. Suggest where to place it in the project
4. Recommend related scripts or components
5. Provide usage examples
Always prioritize:
- Clean, readable code
- Unity performance best practices
- Proper C# conventions
- Clear documentation
- Testability

128
commands/optimize-scene.md Normal file
View File

@@ -0,0 +1,128 @@
You are a Unity performance optimization expert. Analyze the current Unity scene or project and provide comprehensive performance optimization recommendations.
**Your Task:**
When the user runs `/unity:optimize-scene [scene-path]`, you should:
1. **Analyze Scene Structure**
- GameObjects hierarchy depth and complexity
- Number of active GameObjects
- Component usage patterns
- Scene organization
2. **Performance Profiling Areas**
**Rendering:**
- Draw call count and batching opportunities
- Material count and shader complexity
- Texture sizes and compression
- Mesh polygon counts
- Overdraw issues
- Lighting setup (realtime vs baked)
**Physics:**
- Rigidbody count and complexity
- Collider types and optimization
- Physics layers and collision matrix
- Fixed timestep settings
**Scripting:**
- Update/FixedUpdate usage
- GetComponent calls in loops
- String allocations and garbage collection
- Coroutine usage patterns
- Event system overhead
**Memory:**
- Texture memory usage
- Audio clip loading
- Asset bundle management
- Object pooling opportunities
3. **Identify Performance Issues**
- Too many draw calls (> 100 for mobile)
- High polygon count meshes (> 50k triangles)
- Unoptimized textures (not power of 2, too large)
- Missing static batching flags
- Inefficient script patterns
- Memory leaks or excessive allocations
- Missing object pooling
4. **Provide Actionable Recommendations**
**Immediate Fixes:**
- Enable static batching for static objects
- Combine meshes where appropriate
- Compress and resize textures
- Remove unused components
- Optimize shader complexity
**Code Improvements:**
- Cache component references in Awake/Start
- Avoid GetComponent in Update loops
- Use object pooling for frequently spawned objects
- Implement proper coroutine patterns
**Architecture Changes:**
- Implement object pooling for frequently spawned objects
- Use LOD (Level of Detail) systems
- Implement occlusion culling
- Optimize collision detection with layers
- Use event-driven architecture instead of polling
5. **Generate Performance Report**
- Current metrics (draw calls, triangles, GameObjects)
- Critical issues identification
- Prioritized recommendations
- Estimated impact of optimizations
6. **Provide Implementation Guidance**
- Object pooling strategies
- Efficient script patterns
- Memory optimization techniques
7. **Platform-Specific Advice**
- Mobile optimization tips
- PC/Console best practices
- VR performance considerations
- WebGL limitations
8. **Next Steps**
- Prioritized action items
- Profiler usage guidance
- Testing recommendations
- Monitoring strategies
**Example Usage:**
```bash
# Analyze current scene
/unity:optimize-scene
# Analyze specific scene
/unity:optimize-scene Assets/Scenes/MainMenu.unity
# Full project analysis
/unity:optimize-scene --full-project
```
**Analysis Approach:**
1. Read scene files (.unity) if provided
2. Search for common performance issues in scripts
3. Check texture and asset configurations
4. Analyze build settings
5. Review profiler data if available
6. Generate comprehensive report with priorities
**Tools to Use:**
- Read: Scene files, scripts, asset files
- Grep: Search for performance anti-patterns
- Glob: Find large assets, duplicate materials
Always provide:
- Clear problem identification
- Measurable impact estimates
- Prioritized recommendations
- Code examples
- Before/after comparisons

145
commands/setup-test.md Normal file
View File

@@ -0,0 +1,145 @@
You are a Unity testing expert. Set up comprehensive test environments and generate test cases for Unity projects.
**Your Task:**
When the user runs `/unity:setup-test [test-type] [target]`, you should:
1. **Determine Test Type**
- **Unit Tests**: Test individual methods and components in isolation
- **Integration Tests**: Test component interactions
- **PlayMode Tests**: Test runtime behavior in play mode
- **EditMode Tests**: Test editor functionality
- **Performance Tests**: Benchmark and regression testing
2. **Analyze Target Component**
- Read the target script
- Identify public methods to test
- Determine dependencies and mocks needed
- Find edge cases and scenarios
- Check for async operations
3. **Create Test Structure**
- Generate assembly definition file for test project
- Set up proper references to test frameworks (NUnit, Unity Test Runner)
- Configure include/exclude platforms
4. **Generate Test Script**
- NUnit framework with Setup/TearDown
- Arrange-Act-Assert pattern
- Unit tests with [Test] attribute
- PlayMode tests with [UnityTest] for coroutines
- Performance tests with [Performance] attribute
5. **Test Coverage Areas**
**For MonoBehaviours:**
- Initialization (Awake, Start)
- Update loop logic
- Public method behavior
- State transitions
- Collision/Trigger responses
- Coroutine completion
- Event handling
**For ScriptableObjects:**
- Data validation
- Serialization/Deserialization
- Default values
- Method logic
- Edge cases
**For Managers/Systems:**
- Singleton initialization
- State management
- Event dispatching
- Resource loading
- Error handling
6. **Generate Test Cases**
- Happy path scenarios
- Edge cases (null, empty, boundary values)
- Error conditions
- Performance benchmarks
- Regression tests
7. **Mock and Test Doubles**
- Create mock implementations for testing
- Use interfaces for dependency injection
- Track method calls and state changes
8. **Performance Tests**
- Use Unity's Performance Testing package
- Measure method execution time
- Set up benchmarks and regression tests
9. **Setup Instructions**
**Directory Structure:**
```
Assets/
├── Scripts/
│ └── Runtime/
├── Tests/
│ ├── EditMode/
│ │ ├── Tests.asmdef
│ │ └── UtilityTests.cs
│ └── PlayMode/
│ ├── Tests.asmdef
│ └── GameplayTests.cs
```
10. **Test Runner Configuration**
- Test filtering strategies
- Continuous integration setup
- Code coverage tools
- Test report generation
**Example Usage:**
```bash
# Setup unit tests for a script
/unity:setup-test PlayerController
# Setup PlayMode tests
/unity:setup-test playmode PlayerMovement
# Create test suite for system
/unity:setup-test integration InventorySystem
# Setup full test environment
/unity:setup-test --full-project
```
**Output:**
1. Create test directory structure
2. Generate assembly definition files
3. Create comprehensive test script
4. Provide usage documentation
5. Suggest additional test scenarios
6. Explain how to run tests
**Best Practices:**
- **Naming**: `MethodName_Condition_ExpectedResult`
- **Isolation**: Each test independent and deterministic
- **Speed**: Unit tests should be fast (<1ms)
- **Clarity**: Clear arrange-act-assert structure
- **Coverage**: Aim for 80%+ code coverage
- **Maintenance**: Keep tests simple and maintainable
**Testing Principles:**
- Test behavior, not implementation
- One assertion per test (when possible)
- Use descriptive test names
- Mock external dependencies
- Test edge cases and error conditions
- Keep tests independent
Always provide:
- Complete test scripts ready to use
- Clear setup instructions
- Test execution guidance
- Coverage recommendations
- CI/CD integration tips

121
plugin.lock.json Normal file
View File

@@ -0,0 +1,121 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:Dev-GOM/claude-code-marketplace:plugins/unity-dev-toolkit",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "4502929345bbabed504cc773ad3f16ece498a35c",
"treeHash": "918cdd3490d59bb35c7fef038275ef89e7d94e9eb13d22d0260b72b752767e3a",
"generatedAt": "2025-11-28T10:10:17.289469Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "unity-dev-toolkit",
"description": "Unity Development Toolkit - Expert agents for scripting/refactoring/optimization, script templates, and Agent Skills for Unity C# development",
"version": "1.4.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "84e5ccf3b40ddff3ccc19a2d9653ebea274f492277c7eb43b29ce3ab0ac81640"
},
{
"path": "agents/unity-performance.md",
"sha256": "c450eb5b69c81bdec3cd2a1acf574488ca7cf0986d7e7d14dfbbb3f80d572371"
},
{
"path": "agents/unity-refactor.md",
"sha256": "f2135fa07ff9e9486439fe6eb2d698c9ec029c79a85025804f0f7f6896bfc785"
},
{
"path": "agents/unity-scripter.md",
"sha256": "0d5ee3791c36d8af733712c99de30e4c3cabc381d155820484ecca8e668a42bb"
},
{
"path": "agents/unity-architect.md",
"sha256": "c95fd2d5989a6fe29dc9c4e8521a747a92a88c626400ccb530caf611e8700e20"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "19d21547dc0d4763e02a17d0654f9aaa37a111689efd2da209a5d2bcaf418be2"
},
{
"path": "commands/setup-test.md",
"sha256": "327a103060dfb318ad5dbaf932c6eaee3aabb0e512111a89acd698ab44d435a0"
},
{
"path": "commands/new-script.md",
"sha256": "410cc85cc7bf3508ada432b7d7512c0a7a50a747f353416457d5c6d80496e66c"
},
{
"path": "commands/optimize-scene.md",
"sha256": "9bf973032981c165a0d06ba3ccd0a743c4c0ba6d47311c2669e2043683113960"
},
{
"path": "skills/unity-uitoolkit/SKILL.md",
"sha256": "0df613e2f98e241fafea8ed94af3e3badf460a24f480d5ecc37e883ba062a0d9"
},
{
"path": "skills/unity-uitoolkit/ui-toolkit-reference.md",
"sha256": "f67909f06aa573e0711b388351f98334d6ecc19a590d3e718e8bffcc0803f541"
},
{
"path": "skills/unity-scene-optimizer/SKILL.md",
"sha256": "69b8a6951150aac33ef7656786767331f4b96f2438056ab6393a5fb004a12247"
},
{
"path": "skills/unity-script-validator/SKILL.md",
"sha256": "fb96da8dbd11810358310625e76a39a1e0fe359a3b3366b0101ff2746620a090"
},
{
"path": "skills/unity-ui-selector/SKILL.md",
"sha256": "f5a29e04c515c2b03cd71a6e4a3b07177754eb3739828b5ba2d0cae3b22c230a"
},
{
"path": "skills/unity-test-runner/SKILL.md",
"sha256": "a3ec49a874c0d6fe046ce4da1f0a1ab6ea3ad750ec2b092a4676e8db7798c5f4"
},
{
"path": "skills/unity-test-runner/references/test-patterns.json",
"sha256": "2b7dd11947c082dbc39f6f062c835662c7eaccac0d1948444570a99da155d3e8"
},
{
"path": "skills/unity-test-runner/scripts/parse-test-results.js",
"sha256": "81d704f0d95f6f0ecafa273133a207874bb9791644448fa9ec843b23fa60b393"
},
{
"path": "skills/unity-test-runner/scripts/find-unity-editor.js",
"sha256": "75a33684233f41e915a579994a521f87826367e879b2c58a02e7b9ccc033049f"
},
{
"path": "skills/unity-template-generator/SKILL.md",
"sha256": "fe302ab21027cd1c412aa94299bd8ce10ffd85132e1fca47c9c45ff499fbacb1"
},
{
"path": "skills/unity-compile-fixer/SKILL.md",
"sha256": "b9f328efc03a683cedf12d1e7a9e9ce14a847c670b900cc62ae8ca844cdca856"
},
{
"path": "skills/unity-compile-fixer/references/error-patterns.json",
"sha256": "6e6686bd416e8861dc2a824267ec581e3cc08bfc08c17701778976701aef5ae0"
},
{
"path": "skills/unity-compile-fixer/scripts/analyze-diagnostics.js",
"sha256": "fa9160553f50f9066abad4592daad840887c56ce1c9dc799e247e32ae5a23992"
}
],
"dirSha256": "918cdd3490d59bb35c7fef038275ef89e7d94e9eb13d22d0260b72b752767e3a"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

193
skills/unity-compile-fixer/SKILL.md Normal file
View File

@@ -0,0 +1,193 @@
---
name: unity-compile-fixer
description: Detect and resolve Unity C# compilation errors using VSCode diagnostics. Use this skill when Unity projects have compilation errors that need diagnosis and automated fixes. Analyzes errors from VSCode Language Server, proposes solutions based on error patterns, and handles version control conflicts for Unity projects.
---
# Unity Compile Fixer
## Overview
This skill enables automatic detection and resolution of Unity C# compilation errors by leveraging VSCode's diagnostic system. It collects real-time errors from the OmniSharp C# language server, analyzes error patterns against a curated database of common Unity issues, and proposes context-aware solutions for user approval before applying fixes.
## When to Use This Skill
Use this skill when:
- Unity projects report C# compilation errors in VSCode
- Need to diagnose the root cause of Unity compiler errors (CS* error codes)
- Want automated fix suggestions for common Unity scripting issues
- Working with Unity projects that have version control integration (Git, Unity Collaborate, Plastic SCM)
- Need to handle Unity .meta file conflicts
**Example user requests:**
- "Check Unity compilation errors and help me fix them"
- "My Unity project has compiler errors, can you diagnose and fix?"
- "Unity scripts are not compiling, what's wrong?"
- "Fix the C# errors in my Unity project"
## Workflow
Follow this workflow when the skill is invoked:
### 1. Detect Compilation Errors
Use the `mcp__ide__getDiagnostics` tool to collect errors from VSCode:
```typescript
// Collect all project diagnostics
mcp__ide__getDiagnostics()
// Or target specific Unity script files
mcp__ide__getDiagnostics({ uri: "file:///path/to/PlayerController.cs" })
```
Filter the diagnostics to focus on Unity-relevant errors:
- **Severity**: Only process errors with `severity: "Error"` (ignore warnings)
- **Source**: Only process `source: "csharp"` (OmniSharp C# diagnostics)
- **Error Codes**: Focus on CS* compiler error codes (e.g., CS0246, CS0029, CS1061)
### 2. Analyze Error Patterns
For each detected error:
1. **Extract error information:**
- File path and line number from `uri` and `range`
- Error code from `message` (e.g., "CS0246")
- Full error message text
2. **Match against error pattern database:**
- Load `references/error-patterns.json`
- Find the error code entry (e.g., CS0246)
- Retrieve common causes and solutions
3. **Read affected file context:**
- Use Read tool to load the file with errors
- Examine surrounding code for context
- Identify missing imports, incorrect types, or API misuse
### 3. Generate Solution Proposals
For each error, create a structured fix proposal:
```markdown
**Error**: CS0246 at PlayerController.cs:45
**Message**: The type or namespace name 'Rigidbody' could not be found
**Analysis**:
- Missing using directive for UnityEngine namespace
- Common Unity API usage pattern
**Proposed Solution**:
Add `using UnityEngine;` at the top of PlayerController.cs
**Changes Required**:
- File: Assets/Scripts/PlayerController.cs
- Action: Insert using directive at line 1
```
### 4. User Confirmation
Before applying any fixes:
1. **Present all proposed solutions** in a clear, structured format
2. **Use AskUserQuestion tool** to get user approval:
- List each error and proposed fix
- Allow user to approve all, select specific fixes, or cancel
3. **Wait for explicit confirmation** - do not apply fixes automatically
### 5. Apply Approved Fixes
For each approved fix:
1. **Use Edit tool** to modify the affected file
2. **Preserve code formatting** and existing structure
3. **Apply minimal changes** - only fix the specific error
Example:
```typescript
Edit({
file_path: "Assets/Scripts/PlayerController.cs",
old_string: "public class PlayerController : MonoBehaviour",
new_string: "using UnityEngine;\n\npublic class PlayerController : MonoBehaviour"
})
```
### 6. Verify Version Control Status
After applying fixes:
1. **Check for .meta file conflicts:**
- Use Grep to search for Unity .meta files
- Verify that script GUID hasn't changed
- Check for merge conflict markers (<<<<<<, ======, >>>>>>)
2. **Report VCS status:**
- List modified files
- Warn about any .meta file issues
- Suggest git operations if needed
### 7. Re-validate Compilation
After fixes are applied:
1. **Re-run diagnostics** using `mcp__ide__getDiagnostics()`
2. **Compare error count** before and after
3. **Report results** to the user:
- Number of errors fixed
- Remaining errors (if any)
- Success rate
## Error Pattern Database
The skill relies on `references/error-patterns.json` for error analysis. This database contains:
- **Error Code**: CS* compiler error code
- **Description**: Human-readable explanation
- **Common Causes**: Typical reasons this error occurs in Unity
- **Solutions**: Step-by-step fix instructions
- **Unity-Specific Notes**: Unity API considerations
To analyze an error, load the database and match the error code:
```typescript
Read({ file_path: "references/error-patterns.json" })
// Parse JSON and find errorCode entry
```
## Analysis Scripts
The skill includes Node.js scripts in `scripts/` for complex error analysis:
### scripts/analyze-diagnostics.js
Processes VSCode diagnostics JSON output and extracts Unity-relevant errors.
**Usage:**
```bash
node scripts/analyze-diagnostics.js <diagnostics-json-file>
```
**Output:**
- Filtered list of Unity C# compilation errors
- Error classification by type (missing imports, type errors, API issues)
- Severity and file location information
This script can be run independently or invoked from the SKILL.md workflow when detailed analysis is needed.
## Best Practices
When using this skill:
1. **Start with full project diagnostics** - use `mcp__ide__getDiagnostics()` without parameters to get complete error picture
2. **Prioritize errors by severity and dependency** - fix foundational errors (missing imports) before downstream errors
3. **Batch related fixes** - group errors from the same file for efficient editing
4. **Always verify VCS status** - Unity .meta files are critical for version control
5. **Re-validate after fixes** - ensure errors are actually resolved
## Resources
### scripts/analyze-diagnostics.js
Node.js script for processing VSCode diagnostics and filtering Unity-specific C# errors.
### references/error-patterns.json
Curated database of common Unity C# compilation errors with solutions and Unity-specific guidance.

368
skills/unity-compile-fixer/references/error-patterns.json Normal file
View File

@@ -0,0 +1,368 @@
{
"CS0246": {
"errorCode": "CS0246",
"description": "The type or namespace name could not be found",
"commonCauses": [
"Missing using directive (e.g., using UnityEngine;)",
"Assembly definition reference not added",
"Typo in type name",
"Missing package or plugin"
],
"solutions": [
{
"step": 1,
"action": "Add missing using directive",
"example": "using UnityEngine;\nusing UnityEngine.UI;\nusing TMPro;"
},
{
"step": 2,
"action": "Check assembly definition references",
"details": "If using Assembly Definition files (.asmdef), ensure required assemblies are referenced"
},
{
"step": 3,
"action": "Verify type name spelling",
"details": "Check for typos in class, struct, or namespace names"
},
{
"step": 4,
"action": "Install missing packages",
"details": "Open Package Manager and install required Unity packages (TextMeshPro, Input System, etc.)"
}
],
"unityNotes": "Common Unity namespaces: UnityEngine, UnityEngine.UI, UnityEngine.SceneManagement, UnityEditor (editor-only)",
"examples": [
{
"error": "The type or namespace name 'Rigidbody' could not be found",
"fix": "Add 'using UnityEngine;' at the top of the file"
},
{
"error": "The type or namespace name 'TextMeshProUGUI' could not be found",
"fix": "Add 'using TMPro;' and ensure TextMeshPro package is installed"
}
]
},
"CS0029": {
"errorCode": "CS0029",
"description": "Cannot implicitly convert type",
"commonCauses": [
"Assigning incompatible types",
"Missing type cast",
"Incorrect GameObject/Component access",
"Unity API version changes"
],
"solutions": [
{
"step": 1,
"action": "Add explicit cast",
"example": "Rigidbody rb = (Rigidbody)GetComponent(typeof(Rigidbody));"
},
{
"step": 2,
"action": "Use generic GetComponent",
"example": "Rigidbody rb = GetComponent<Rigidbody>();"
},
{
"step": 3,
"action": "Check variable type declaration",
"details": "Ensure variable type matches assigned value type"
}
],
"unityNotes": "Unity uses generic methods extensively. Prefer GetComponent<T>() over non-generic versions",
"examples": [
{
"error": "Cannot implicitly convert type 'UnityEngine.Component' to 'UnityEngine.Rigidbody'",
"fix": "Use GetComponent<Rigidbody>() instead of GetComponent(typeof(Rigidbody))"
}
]
},
"CS1061": {
"errorCode": "CS1061",
"description": "Type does not contain a definition for member",
"commonCauses": [
"Typo in method or property name",
"Unity API version difference",
"Accessing wrong object type",
"Missing component reference"
],
"solutions": [
{
"step": 1,
"action": "Check spelling and capitalization",
"details": "C# is case-sensitive. Ensure method/property name is correct"
},
{
"step": 2,
"action": "Verify Unity API version",
"details": "Some APIs change between Unity versions. Check Unity documentation"
},
{
"step": 3,
"action": "Ensure correct component type",
"example": "transform.position (correct) vs gameObject.position (incorrect)"
},
{
"step": 4,
"action": "Use correct Unity API",
"details": "GameObject vs Component vs Transform have different members"
}
],
"unityNotes": "Common confusion: GameObject.transform.position (correct) vs GameObject.position (incorrect)",
"examples": [
{
"error": "'GameObject' does not contain a definition for 'position'",
"fix": "Use 'transform.position' or 'gameObject.transform.position'"
},
{
"error": "'Rigidbody' does not contain a definition for 'Translate'",
"fix": "Use 'transform.Translate()' instead - Translate is a Transform method, not Rigidbody"
}
]
},
"CS0101": {
"errorCode": "CS0101",
"description": "The namespace already contains a definition",
"commonCauses": [
"Duplicate class names in same namespace",
"Partial class definitions conflict",
"Multiple files with same class name",
"Copy-pasted scripts not renamed"
],
"solutions": [
{
"step": 1,
"action": "Rename one of the conflicting classes",
"details": "Each class in a namespace must have a unique name"
},
{
"step": 2,
"action": "Move class to different namespace",
"example": "namespace MyGame.Player { class Controller { } }"
},
{
"step": 3,
"action": "Check for duplicate files",
"details": "Search project for files with same class name"
}
],
"unityNotes": "Unity script file names should match class names. Rename both file and class together",
"examples": [
{
"error": "The namespace 'MyGame' already contains a definition for 'PlayerController'",
"fix": "Rename one class to 'PlayerMovement' or use different namespaces"
}
]
},
"CS1002": {
"errorCode": "CS1002",
"description": "Expected semicolon",
"commonCauses": [
"Missing semicolon at end of statement",
"Incomplete method call",
"Syntax error in expression"
],
"solutions": [
{
"step": 1,
"action": "Add missing semicolon",
"example": "int health = 100; // semicolon required"
},
{
"step": 2,
"action": "Check line above error",
"details": "Error often reported on line after the actual missing semicolon"
}
],
"unityNotes": "Check Unity lifecycle methods (Start, Update) for missing semicolons",
"examples": [
{
"error": "Expected ';' after 'transform.position = newPos'",
"fix": "Add semicolon: transform.position = newPos;"
}
]
},
"CS1003": {
"errorCode": "CS1003",
"description": "Syntax error, expected comma",
"commonCauses": [
"Missing comma in parameter list",
"Missing comma in array initialization",
"Incorrect method signature"
],
"solutions": [
{
"step": 1,
"action": "Add missing comma",
"example": "Vector3 pos = new Vector3(1.0f, 2.0f, 3.0f);"
},
{
"step": 2,
"action": "Check method parameters",
"details": "Ensure parameters are separated by commas"
}
],
"unityNotes": "Unity methods like Vector3, Quaternion require commas between components",
"examples": [
{
"error": "Expected ',' in Vector3 constructor",
"fix": "new Vector3(1.0f, 2.0f, 3.0f) // commas required"
}
]
},
"CS1525": {
"errorCode": "CS1525",
"description": "Invalid expression term",
"commonCauses": [
"Keyword used in wrong context",
"Incomplete expression",
"Missing opening brace"
],
"solutions": [
{
"step": 1,
"action": "Check for matching braces",
"details": "Ensure all { } are properly matched"
},
{
"step": 2,
"action": "Verify expression syntax",
"details": "Check for incomplete or malformed expressions"
}
],
"unityNotes": "Common in Unity lifecycle methods - ensure proper { } around method bodies",
"examples": [
{
"error": "Invalid expression term 'void'",
"fix": "Check for missing brace before method definition"
}
]
},
"CS0122": {
"errorCode": "CS0122",
"description": "Member is inaccessible due to its protection level",
"commonCauses": [
"Accessing private member from outside class",
"Missing public/protected modifier",
"Incorrect inheritance setup"
],
"solutions": [
{
"step": 1,
"action": "Change member to public",
"example": "public float speed = 5.0f;"
},
{
"step": 2,
"action": "Use SerializeField for private fields",
"example": "[SerializeField] private float speed;"
},
{
"step": 3,
"action": "Add public property or method",
"example": "public float Speed { get { return speed; } }"
}
],
"unityNotes": "Use [SerializeField] for private fields that should appear in Inspector",
"examples": [
{
"error": "'PlayerController.speed' is inaccessible due to its protection level",
"fix": "Change 'private float speed;' to 'public float speed;' or add [SerializeField]"
}
]
},
"CS0103": {
"errorCode": "CS0103",
"description": "The name does not exist in the current context",
"commonCauses": [
"Variable not declared",
"Typo in variable name",
"Variable out of scope",
"Missing component reference"
],
"solutions": [
{
"step": 1,
"action": "Declare variable before use",
"example": "Rigidbody rb;\nvoid Start() { rb = GetComponent<Rigidbody>(); }"
},
{
"step": 2,
"action": "Check variable name spelling",
"details": "Variable names are case-sensitive"
},
{
"step": 3,
"action": "Ensure variable is in scope",
"details": "Variables declared in methods are only accessible within that method"
}
],
"unityNotes": "Common with component references - ensure they're declared as class fields",
"examples": [
{
"error": "The name 'rb' does not exist in the current context",
"fix": "Declare 'Rigidbody rb;' at class level before using in methods"
}
]
},
"CS0119": {
"errorCode": "CS0119",
"description": "Member is a type, which is not valid in the given context",
"commonCauses": [
"Using type name instead of instance",
"Missing instantiation",
"Incorrect static/instance usage"
],
"solutions": [
{
"step": 1,
"action": "Create instance of type",
"example": "GameObject player = new GameObject(); // not just 'GameObject'"
},
{
"step": 2,
"action": "Use correct Unity API",
"example": "GameObject.Find('Player') // static method on type"
}
],
"unityNotes": "Unity has both static methods (GameObject.Find) and instance methods (gameObject.SetActive)",
"examples": [
{
"error": "'GameObject' is a type but is used like a variable",
"fix": "Use 'gameObject' (lowercase - current instance) or 'new GameObject()'"
}
]
},
"CS0117": {
"errorCode": "CS0117",
"description": "Type does not contain a definition",
"commonCauses": [
"Unity API version change",
"Incorrect class/namespace",
"Missing package reference"
],
"solutions": [
{
"step": 1,
"action": "Check Unity documentation",
"details": "API may have changed in your Unity version"
},
{
"step": 2,
"action": "Verify class name",
"details": "Ensure using correct Unity class"
},
{
"step": 3,
"action": "Update deprecated APIs",
"details": "Some APIs are replaced in newer Unity versions"
}
],
"unityNotes": "Unity 2020+ changed many APIs. Check Unity Upgrade Guide",
"examples": [
{
"error": "'Input' does not contain a definition for 'GetKey'",
"fix": "In new Input System, use 'Keyboard.current.spaceKey.isPressed' instead"
}
]
}
}

228
skills/unity-compile-fixer/scripts/analyze-diagnostics.js Normal file
View File

@@ -0,0 +1,228 @@
#!/usr/bin/env node
/**
* Unity Compile Error Analyzer
*
* Processes VSCode diagnostics JSON output and extracts Unity-relevant C# compilation errors.
* Filters by severity (Error only), source (csharp), and classifies errors by type.
*
* Usage:
* node analyze-diagnostics.js <diagnostics-json-file>
* node analyze-diagnostics.js (reads from stdin)
*
* Output: JSON array of classified Unity errors
*/
const fs = require('fs');
const path = require('path');
// Error classification patterns
const ERROR_CLASSIFICATIONS = {
MISSING_IMPORT: {
patterns: [/CS0246/, /type or namespace.*could not be found/i],
category: 'Missing Import/Namespace',
priority: 1
},
TYPE_MISMATCH: {
patterns: [/CS0029/, /cannot implicitly convert/i, /cannot convert type/i],
category: 'Type Mismatch',
priority: 2
},
MEMBER_NOT_FOUND: {
patterns: [/CS1061/, /does not contain a definition/i],
category: 'Member Not Found',
priority: 2
},
DUPLICATE_DEFINITION: {
patterns: [/CS0101/, /already contains a definition/i],
category: 'Duplicate Definition',
priority: 3
},
SYNTAX_ERROR: {
patterns: [/CS1002/, /CS1003/, /CS1525/, /expected/i],
category: 'Syntax Error',
priority: 1
},
ACCESS_MODIFIER: {
patterns: [/CS0122/, /inaccessible due to its protection level/i],
category: 'Access Modifier Issue',
priority: 2
},
UNITY_API: {
patterns: [/MonoBehaviour/, /GameObject/, /Transform/, /Component/],
category: 'Unity API Issue',
priority: 1
}
};
/**
* Classify error based on message content
*/
function classifyError(message) {
for (const [key, classifier] of Object.entries(ERROR_CLASSIFICATIONS)) {
for (const pattern of classifier.patterns) {
if (pattern.test(message)) {
return {
type: key,
category: classifier.category,
priority: classifier.priority
};
}
}
}
return {
type: 'UNKNOWN',
category: 'Other Error',
priority: 4
};
}
/**
* Extract error code from message (e.g., "CS0246")
*/
function extractErrorCode(message) {
const match = message.match(/CS\d{4}/);
return match ? match[0] : null;
}
/**
* Filter and process diagnostics
*/
function analyzeDiagnostics(diagnostics) {
if (!diagnostics || !Array.isArray(diagnostics)) {
console.error('Error: Invalid diagnostics format. Expected array.');
process.exit(1);
}
const unityErrors = diagnostics
.filter(diag => {
// Filter: Only errors (not warnings)
if (diag.severity !== 'Error') return false;
// Filter: Only C# errors from OmniSharp
if (diag.source !== 'csharp') return false;
// Filter: Must have valid message
if (!diag.message) return false;
return true;
})
.map(diag => {
const classification = classifyError(diag.message);
const errorCode = extractErrorCode(diag.message);
return {
file: diag.uri ? diag.uri.replace('file:///', '') : 'unknown',
line: diag.range?.start?.line ?? 0,
column: diag.range?.start?.character ?? 0,
errorCode: errorCode,
message: diag.message,
classification: classification.category,
type: classification.type,
priority: classification.priority,
source: diag.source
};
});
// Sort by priority (lower number = higher priority)
unityErrors.sort((a, b) => a.priority - b.priority);
return unityErrors;
}
/**
* Generate summary statistics
*/
function generateSummary(errors) {
const summary = {
totalErrors: errors.length,
byCategory: {},
byFile: {},
highPriority: errors.filter(e => e.priority === 1).length
};
errors.forEach(error => {
// Count by category
summary.byCategory[error.classification] =
(summary.byCategory[error.classification] || 0) + 1;
// Count by file
const fileName = path.basename(error.file);
summary.byFile[fileName] = (summary.byFile[fileName] || 0) + 1;
});
return summary;
}
/**
* Main execution
*/
function main() {
const args = process.argv.slice(2);
let diagnosticsData;
if (args.length === 0) {
// Read from stdin
console.error('Reading diagnostics from stdin...');
const input = fs.readFileSync(0, 'utf-8');
try {
diagnosticsData = JSON.parse(input);
} catch (error) {
console.error('Error parsing JSON from stdin:', error.message);
process.exit(1);
}
} else {
// Read from file
const filePath = args[0];
if (!fs.existsSync(filePath)) {
console.error(`Error: File not found: ${filePath}`);
process.exit(1);
}
try {
const fileContent = fs.readFileSync(filePath, 'utf-8');
diagnosticsData = JSON.parse(fileContent);
} catch (error) {
console.error(`Error reading/parsing file: ${error.message}`);
process.exit(1);
}
}
// Extract diagnostics array (handle different formats)
let diagnostics;
if (Array.isArray(diagnosticsData)) {
diagnostics = diagnosticsData;
} else if (diagnosticsData.diagnostics && Array.isArray(diagnosticsData.diagnostics)) {
diagnostics = diagnosticsData.diagnostics;
} else {
console.error('Error: Could not find diagnostics array in input');
process.exit(1);
}
// Analyze
const errors = analyzeDiagnostics(diagnostics);
const summary = generateSummary(errors);
// Output results
const output = {
summary: summary,
errors: errors
};
console.log(JSON.stringify(output, null, 2));
}
// Run if executed directly
if (require.main === module) {
main();
}
// Export for use as module
module.exports = {
analyzeDiagnostics,
classifyError,
extractErrorCode,
generateSummary
};

73
skills/unity-scene-optimizer/SKILL.md Normal file
View File

@@ -0,0 +1,73 @@
---
name: Unity Scene Optimizer
description: Analyzes scenes for performance bottlenecks (draw calls, batching, textures, GameObjects). Use when optimizing scenes or investigating performance issues.
allowed-tools: Read, Grep, Glob
---
# Unity Scene Optimizer
Analyzes Unity scenes and provides performance optimization recommendations for rendering, physics, memory, and platform-specific concerns.
## What This Skill Analyzes
### 1. Rendering Performance
Analyzes draw calls (target: <100 mobile, <2000 desktop), identifies batching opportunities, recommends material consolidation and static batching.
### 2. Texture Optimization
Reviews compression formats (BC7/ASTC), mipmap usage, texture atlasing, and platform-specific import settings.
### 3. GameObject Hierarchy
Targets: <500 GameObjects mobile, <2000 desktop. Identifies deep nesting, recommends object pooling and LOD groups.
### 4. Lighting and Shadows
Recommends baked lighting over realtime (1-2 lights mobile, 3-4 desktop), minimal shadow-casting lights.
### 5. Physics Optimization
Analyzes Rigidbody count, collider complexity, collision matrix configuration. Recommends simple colliders over Mesh colliders.
### 6. Mobile-Specific
Platform targets: 60 FPS iOS (iPhone 12+), 30-60 FPS Android. See [mobile-checklist.md](mobile-checklist.md) for complete requirements.
## Optimization Workflow
1. **Measure**: Frame Debugger, Stats, Profiler metrics
2. **Identify**: GPU/CPU/Memory/Physics bottlenecks
3. **Apply**: Quick wins (static batching, compression) → Medium (atlases, pooling, LOD) → Major (hierarchy refactor, culling)
4. **Validate**: Compare before/after metrics
See [optimization-workflow.md](optimization-workflow.md) for detailed steps and timelines.
## Platform-Specific Targets
| Platform | Draw Calls | Triangles | Texture Memory | Lights |
|----------|-----------|-----------|----------------|--------|
| **Mobile Low** | <50 | <20k | <100MB | 1 |
| **Mobile Mid** | <100 | <50k | <250MB | 1-2 |
| **Mobile High** | <150 | <100k | <500MB | 2-3 |
| **PC Low** | <500 | <200k | <1GB | 3-4 |
| **PC Mid** | <1000 | <500k | <2GB | 4-6 |
| **PC High** | <2000 | <1M | <4GB | 6-8 |
| **Console** | <1000 | <800k | <3GB | 4-6 |
## Tools Reference
Frame Debugger, Profiler, Stats Window, Memory Profiler. See [tools-reference.md](tools-reference.md) for usage and commands.
## Output Format
Provides: Current metrics, bottleneck identification, prioritized recommendations, performance impact estimates, implementation steps.
## When to Use vs Other Components
**Use this Skill when**: Analyzing scene performance, identifying bottlenecks, or getting optimization recommendations
**Use @unity-performance agent when**: Implementing complex optimizations, profiling at runtime, or troubleshooting specific performance issues
**Use @unity-architect agent when**: Redesigning scene architecture, implementing object pooling systems, or planning large-scale optimizations
**Use /unity:optimize-scene command when**: Running comprehensive scene analysis with detailed reports
## Related Skills
- **unity-script-validator**: For script-level performance issues
- **unity-template-generator**: For optimized component templates

45
skills/unity-script-validator/SKILL.md Normal file
View File

@@ -0,0 +1,45 @@
---
name: Unity Script Validator
description: Validates C# scripts for best practices, performance, and Unity patterns. Use when reviewing scripts or checking code quality.
allowed-tools: Read, Grep, Glob
---
# Unity Script Validator
Validates Unity C# scripts against best practices and performance patterns specific to Unity game development.
## What This Skill Checks
- **Field declarations**: `[SerializeField] private` instead of public fields
- **Component caching**: GetComponent in Awake/Start, not Update (~100x faster)
- **String operations**: StringBuilder for frequent concatenation
- **GameObject.Find**: Cache references, avoid in Update (O(n) operation)
- **Code organization**: #region directives, consistent ordering
- **XML documentation**: `<summary>` tags on public methods
- **Update vs FixedUpdate**: Appropriate usage for physics/non-physics
- **Coroutines**: Prefer for intermittent tasks over Update
Provides: Issues found, specific fixes, performance impact estimates, refactored code examples.
## Compatibility
Applies to Unity 2019.4 LTS and later (including Unity 6).
See [patterns.md](patterns.md) and [examples.md](examples.md) for detailed optimization techniques.
## When to Use vs Other Components
**Use this Skill when**: Quick validation of existing Unity scripts for best practices and common issues
**Use @unity-scripter agent when**: Writing new code or implementing Unity features from scratch
**Use @unity-refactor agent when**: Improving code quality, applying design patterns, or modernizing legacy code
**Use @unity-performance agent when**: Deep performance profiling, memory optimization, or platform-specific tuning
**Use /unity:new-script command when**: Creating new scripts from production-ready templates
## Related Skills
- **unity-scene-optimizer**: For scene-level performance analysis
- **unity-template-generator**: For generating validated script templates

49
skills/unity-template-generator/SKILL.md Normal file
View File

@@ -0,0 +1,49 @@
---
name: Unity Template Generator
description: Generates production-ready C# script templates (MonoBehaviour, ScriptableObject, Editor, tests). Use when creating new scripts or setting up project structure.
allowed-tools: Write, Read, Glob
---
# Unity Template Generator
Assists with generating production-ready Unity C# script templates that follow best practices and Unity conventions.
## Available Templates
**MonoBehaviour** - GameObject components with lifecycle methods, serialized fields, component caching, and Gizmo helpers.
**ScriptableObject** - Data assets with `[CreateAssetMenu]`, validation, encapsulation, and clone methods.
**Editor Script** - Custom inspectors or windows. Asks for UGUI vs UI Toolkit preference (see [unity-ui-selector](../unity-ui-selector/SKILL.md)).
**Test Script** - NUnit/PlayMode tests with Setup/TearDown, `[UnityTest]`, performance tests, and Arrange-Act-Assert pattern.
## Template Features
All templates include:
- Unity coding conventions (`[SerializeField]`, PascalCase, XML docs)
- Performance patterns (component caching, no GetComponent in Update)
- Code organization (#region directives, consistent ordering)
- Safety features (null checks, OnValidate, Gizmos)
Placeholders: `{{CLASS_NAME}}`, `{{NAMESPACE}}`, `{{DESCRIPTION}}`, `{{MENU_PATH}}`, `{{FILE_NAME}}`
See [template-reference.md](template-reference.md) for detailed customization options.
## When to Use vs Other Components
**Use this Skill when**: Discussing template options, understanding template features, or getting guidance on script structure
**Use @unity-scripter agent when**: Writing custom scripts with specific requirements or implementing complex Unity features
**Use @unity-refactor agent when**: Improving existing scripts or restructuring code for better maintainability
**Use /unity:new-script command when**: Actually generating script files from templates with specific parameters
**Use /unity:setup-test command when**: Setting up complete test environments with test scripts
## Related Skills
- **unity-script-validator**: Validates generated scripts
- **unity-ui-selector**: Helps choose UI system for Editor scripts
- **unity-uitoolkit**: Assists with UI Toolkit implementation when generating Editor scripts

424
skills/unity-test-runner/SKILL.md Normal file
View File

@@ -0,0 +1,424 @@
---
name: unity-test-runner
description: Execute and analyze Unity Test Framework tests from the command line. This skill automates test execution for Unity projects by detecting the Unity Editor, configuring test parameters (EditMode/PlayMode), running tests via CLI, parsing XML results, and generating detailed failure reports. Use this when running Unity tests, validating game logic, or debugging test failures.
---
# Unity Test Runner
## Overview
This skill enables automated execution and analysis of Unity Test Framework tests directly from the command line. It handles the complete test workflow: detecting Unity Editor installations across platforms (Windows/macOS/Linux), configuring test parameters, executing tests in EditMode or PlayMode, parsing NUnit XML results, and generating detailed failure reports with actionable insights.
## When to Use This Skill
Use this skill when:
- Executing Unity Test Framework tests from command line
- Running PlayMode or EditMode tests for game logic validation
- Analyzing test failures and generating failure reports
- Integrating Unity tests into CI/CD pipelines
- Debugging test failures with detailed stack traces and file locations
- Validating Unity project changes before commits
**Example user requests:**
- "Run all Unity tests in my project"
- "Execute PlayMode tests and show me the results"
- "Run tests in the Combat category"
- "Check if my Unity tests are passing"
- "Run EditMode tests only"
## Workflow
Follow this workflow when the skill is invoked:
### 1. Detect Unity Editor Installation
Use the `find-unity-editor.js` script to automatically locate the Unity Editor:
```bash
node scripts/find-unity-editor.js --json
```
**Script behavior:**
- Scans platform-specific default installation paths
- Detects all installed Unity versions
- Returns the latest version by default
- Can target specific version with `--version <version>` flag
**Output:**
```json
{
"found": true,
"editorPath": "C:\\Program Files\\Unity\\Hub\\Editor\\2021.3.15f1\\Editor\\Unity.exe",
"version": "2021.3.15f1",
"platform": "win32",
"allVersions": ["2021.3.15f1", "2020.3.30f1"]
}
```
**If multiple versions are found:**
1. Present all available versions to the user
2. Ask user to confirm which version to use
3. Or use the latest version by default
**If no Unity Editor is found:**
- Report error with searched paths
- Ask user to provide Unity Editor path manually
- Store the path for future use
### 2. Verify Unity Project Path
Confirm the current directory contains a valid Unity project using cross-platform checks:
```typescript
// Use Read tool to check for Unity project indicators
Read({ file_path: "ProjectSettings/ProjectVersion.txt" })
// Use Glob to verify Assets directory exists
Glob({ pattern: "Assets/*", path: "." })
```
**Validation steps:**
1. Verify `Assets/` directory exists
2. Verify `ProjectSettings/ProjectVersion.txt` exists
3. Read `ProjectVersion.txt` to get Unity version
4. Warn if Editor version doesn't match project version
**Example ProjectVersion.txt:**
```
m_EditorVersion: 2021.3.15f1
m_EditorVersionWithRevision: 2021.3.15f1 (e8e88743f9e5)
```
### 3. Configure Test Settings
Determine test execution parameters. Use `AskUserQuestion` tool if parameters are not specified:
**Required settings:**
- **Test Mode**: EditMode, PlayMode, or Both
- **Test Platform**: EditMode tests use "EditMode", PlayMode can specify platform (e.g., "StandaloneWindows64", "Android", "iOS")
**Optional settings:**
- **Test Categories**: Semicolon-separated list (e.g., "Combat;AI;Physics")
- **Test Filter**: Regex pattern or semicolon-separated test names
- **Results Output Path**: Default to `TestResults.xml` in project root
**Configuration example:**
```typescript
AskUserQuestion({
questions: [{
question: "Which test mode should be executed?",
header: "Test Mode",
multiSelect: false,
options: [
{ label: "EditMode Only", description: "Fast unit tests without Play Mode" },
{ label: "PlayMode Only", description: "Full Unity engine tests" },
{ label: "Both Modes", description: "Run all tests (slower)" }
]
}]
})
```
### 4. Execute Tests via Command Line
Build and execute the Unity command line test command:
**Command structure:**
```bash
<UnityEditorPath> -runTests -batchmode -projectPath <ProjectPath> \
-testPlatform <EditMode|PlayMode> \
-testResults <OutputPath> \
[-testCategory <Categories>] \
[-testFilter <Filter>] \
-logFile -
```
**Example commands:**
**EditMode tests:**
```bash
"C:\Program Files\Unity\Hub\Editor\2021.3.15f1\Editor\Unity.exe" \
-runTests -batchmode \
-projectPath "D:\Projects\MyGame" \
-testPlatform EditMode \
-testResults "TestResults-EditMode.xml" \
-logFile -
```
**PlayMode tests with category filter:**
```bash
"C:\Program Files\Unity\Hub\Editor\2021.3.15f1\Editor\Unity.exe" \
-runTests -batchmode \
-projectPath "D:\Projects\MyGame" \
-testPlatform PlayMode \
-testResults "TestResults-PlayMode.xml" \
-testCategory "Combat;AI" \
-logFile -
```
**Execution notes:**
- Use `Bash` tool with `run_in_background: true` for long-running tests
- Set timeout appropriately (default: 5-10 minutes, adjust based on test count)
- Monitor output for progress indicators
- Capture both stdout and stderr
**Example execution:**
```typescript
Bash({
command: `"${unityPath}" -runTests -batchmode -projectPath "${projectPath}" -testPlatform EditMode -testResults "TestResults.xml" -logFile -`,
description: "Execute Unity EditMode tests",
timeout: 300000, // 5 minutes
run_in_background: true
})
```
### 5. Parse Test Results
After tests complete, parse the NUnit XML results using `parse-test-results.js`:
```bash
node scripts/parse-test-results.js TestResults.xml --json
```
**Script output:**
```json
{
"summary": {
"total": 10,
"passed": 7,
"failed": 2,
"skipped": 1,
"duration": 12.345
},
"failures": [
{
"name": "TestPlayerTakeDamage",
"fullName": "Tests.Combat.PlayerTests.TestPlayerTakeDamage",
"message": "Expected: 90\n But was: 100",
"stackTrace": "at Tests.Combat.PlayerTests.TestPlayerTakeDamage () [0x00001] in Assets/Tests/Combat/PlayerTests.cs:42",
"file": "Assets/Tests/Combat/PlayerTests.cs",
"line": 42
}
],
"allTests": [...]
}
```
**Result analysis:**
1. Extract test summary statistics
2. Identify all failed tests
3. Extract file paths and line numbers from stack traces
4. Categorize failures by type (assertion, exception, timeout)
### 6. Analyze Test Failures
For each failed test, analyze the failure using `references/test-patterns.json`:
**Analysis steps:**
1. **Load test patterns database:**
```typescript
Read({ file_path: "references/test-patterns.json" })
```
2. **Match failure message against patterns:**
- Assertion failures: `Expected: <X> But was: <Y>`
- Null reference failures: `Expected: not null But was: <null>`
- Timeout failures: `TimeoutException|Test exceeded time limit`
- Threading errors: `Can't be called from.*main thread`
- Object lifetime issues: `has been destroyed|MissingReferenceException`
3. **Determine failure category:**
- ValueMismatch: Incorrect assertion value
- NullValue: Unexpected null reference
- Performance: Timeout or slow execution
- TestSetup: Setup/TearDown failure
- ObjectLifetime: Destroyed object access
- Threading: Wrong thread execution
4. **Generate fix suggestions:**
- Load common solutions from test-patterns.json
- Match solutions to failure pattern
- Provide concrete code examples
**Example failure analysis:**
```markdown
**Test**: Tests.Combat.PlayerTests.TestPlayerTakeDamage
**Location**: Assets/Tests/Combat/PlayerTests.cs:42
**Result**: FAILED
**Failure Message**:
Expected: 90
But was: 100
**Analysis**:
- Category: ValueMismatch (Assertion Failure)
- Pattern: Expected/actual value mismatch
- Root Cause: Player health not decreasing after TakeDamage() call
**Possible Causes**:
1. TakeDamage() method not implemented correctly
2. Player health not initialized properly
3. Damage value passed incorrectly
**Suggested Solutions**:
1. Verify TakeDamage() implementation:
```csharp
public void TakeDamage(int damage) {
health -= damage; // Ensure this line exists
}
```
2. Check test setup:
```csharp
[SetUp]
public void SetUp() {
player = new Player();
player.Health = 100; // Ensure proper initialization
}
```
3. Verify test assertion:
```csharp
player.TakeDamage(10);
Assert.AreEqual(90, player.Health); // Expected: 90
```
```
### 7. Generate Test Report
Create a comprehensive test report for the user:
**Report structure:**
```markdown
# Unity Test Results
## Summary
- **Total Tests**: 10
- **✓ Passed**: 7 (70%)
- **✗ Failed**: 2 (20%)
- **⊘ Skipped**: 1 (10%)
- **Duration**: 12.35s
## Test Breakdown
- **EditMode Tests**: 5 passed, 1 failed
- **PlayMode Tests**: 2 passed, 1 failed
## Failed Tests
### 1. Tests.Combat.PlayerTests.TestPlayerTakeDamage
**Location**: Assets/Tests/Combat/PlayerTests.cs:42
**Failure**: Expected: 90, But was: 100
**Analysis**: Player health not decreasing after TakeDamage() call.
**Suggested Fix**: Verify TakeDamage() implementation decreases health correctly.
---
### 2. Tests.AI.EnemyTests.TestEnemyChasePlayer
**Location**: Assets/Tests/AI/EnemyTests.cs:67
**Failure**: TimeoutException - Test exceeded time limit (5s)
**Analysis**: Infinite loop or missing yield in coroutine test.
**Suggested Fix**: Add `[UnityTest]` attribute and use `yield return null` in test loop.
---
## Next Steps
1. Review failed test locations and fix implementation
2. Re-run tests after fixes by re-invoking the skill
3. Consider adding more assertions for edge cases
```
**Report delivery:**
- Present report in formatted Markdown
- Highlight critical failures
- Provide file:line references for quick navigation
- Offer to help fix specific failures if user requests
## Best Practices
When using this skill:
1. **Run EditMode tests first** - They're faster and catch basic logic errors
- Reserve PlayMode tests for Unity-specific features
- Use EditMode for pure C# logic and data structures
2. **Use test categories** - Filter tests for faster iteration
- `-testCategory "Combat"` runs only Combat tests
- Helpful during active development of specific features
3. **Monitor test duration** - Set appropriate timeouts
- EditMode: 1-3 minutes typical
- PlayMode: 5-15 minutes typical
- Adjust timeout based on test count
4. **Check Unity version compatibility** - Ensure Editor matches project version
- Mismatched versions may cause test failures
- Test results may be inconsistent across versions
5. **Parse results immediately** - Don't wait for manual review
- Automated parsing catches issues faster
- Provides actionable file:line information
6. **Analyze failure patterns** - Look for common causes
- Similar failures often indicate systemic issues
- Fix root cause instead of individual symptoms
7. **Preserve test results** - Keep XML files for debugging
- Results contain full stack traces
- Useful for comparing test runs
8. **Handle long-running tests** - Use background execution
- Monitor progress with `BashOutput` tool
- Provide status updates to user
## Resources
### scripts/find-unity-editor.js
Cross-platform Unity Editor path detection script. Automatically scans default installation directories for Windows, macOS, and Linux, detects all installed Unity versions, and returns the latest version or a specific requested version.
**Usage:**
```bash
# Find latest Unity version
node scripts/find-unity-editor.js --json
# Find specific version
node scripts/find-unity-editor.js --version 2021.3.15f1 --json
```
**Output**: JSON with Unity Editor path, version, platform, and all available versions.
### scripts/parse-test-results.js
NUnit XML results parser for Unity Test Framework output. Extracts test statistics, failure details, stack traces, and file locations from XML results.
**Usage:**
```bash
# Parse test results with JSON output
node scripts/parse-test-results.js TestResults.xml --json
# Parse with formatted console output
node scripts/parse-test-results.js TestResults.xml
```
**Output**: JSON with test summary, failure details including file paths and line numbers, and full test list.
### references/test-patterns.json
Comprehensive database of Unity testing patterns, NUnit assertions, common failure patterns, and best practices. Includes:
- NUnit assertion reference (equality, collections, exceptions, Unity-specific)
- Common failure patterns with regex matching
- Failure categories and root cause analysis
- Solution templates with code examples
- EditMode vs PlayMode guidance
- Unity-specific testing patterns (coroutines, scenes, prefabs, physics)
- Testing best practices
**Usage**: Load this file when analyzing test failures to match failure messages against patterns and generate fix suggestions.

384
skills/unity-test-runner/references/test-patterns.json Normal file
View File

@@ -0,0 +1,384 @@
{
"nunitAssertions": {
"equality": {
"assertions": [
{
"method": "Assert.AreEqual(expected, actual)",
"description": "Verifies that two values are equal",
"example": "Assert.AreEqual(100, player.Health);"
},
{
"method": "Assert.AreNotEqual(expected, actual)",
"description": "Verifies that two values are not equal",
"example": "Assert.AreNotEqual(0, enemy.Speed);"
}
]
},
"identity": {
"assertions": [
{
"method": "Assert.AreSame(expected, actual)",
"description": "Verifies that two objects refer to the same object instance",
"example": "Assert.AreSame(playerInstance, savedPlayer);"
},
{
"method": "Assert.AreNotSame(expected, actual)",
"description": "Verifies that two objects do not refer to the same object instance",
"example": "Assert.AreNotSame(player1, player2);"
}
]
},
"nullity": {
"assertions": [
{
"method": "Assert.IsNull(object)",
"description": "Verifies that an object is null",
"example": "Assert.IsNull(destroyedEnemy);"
},
{
"method": "Assert.IsNotNull(object)",
"description": "Verifies that an object is not null",
"example": "Assert.IsNotNull(spawnedPlayer);"
}
]
},
"boolean": {
"assertions": [
{
"method": "Assert.IsTrue(condition)",
"description": "Verifies that a condition is true",
"example": "Assert.IsTrue(player.IsAlive);"
},
{
"method": "Assert.IsFalse(condition)",
"description": "Verifies that a condition is false",
"example": "Assert.IsFalse(enemy.IsInvincible);"
}
]
},
"collections": {
"assertions": [
{
"method": "Assert.Contains(item, collection)",
"description": "Verifies that a collection contains a specific item",
"example": "Assert.Contains(weapon, inventory.Items);"
},
{
"method": "CollectionAssert.AreEqual(expected, actual)",
"description": "Verifies that two collections are equal",
"example": "CollectionAssert.AreEqual(expectedItems, actualItems);"
},
{
"method": "CollectionAssert.IsEmpty(collection)",
"description": "Verifies that a collection is empty",
"example": "CollectionAssert.IsEmpty(emptyInventory);"
},
{
"method": "CollectionAssert.IsNotEmpty(collection)",
"description": "Verifies that a collection is not empty",
"example": "CollectionAssert.IsNotEmpty(player.Skills);"
}
]
},
"exceptions": {
"assertions": [
{
"method": "Assert.Throws<TException>(() => { code })",
"description": "Verifies that a specific exception type is thrown",
"example": "Assert.Throws<ArgumentNullException>(() => player.Attack(null));"
},
{
"method": "Assert.DoesNotThrow(() => { code })",
"description": "Verifies that no exception is thrown",
"example": "Assert.DoesNotThrow(() => player.Move(Vector3.zero));"
}
]
},
"unity": {
"assertions": [
{
"method": "LogAssert.Expect(LogType, message)",
"description": "Expects a specific Unity log message",
"example": "LogAssert.Expect(LogType.Warning, \"Player health low\");"
},
{
"method": "LogAssert.NoUnexpectedReceived()",
"description": "Verifies no unexpected log messages were received",
"example": "LogAssert.NoUnexpectedReceived();"
}
]
}
},
"commonFailurePatterns": [
{
"pattern": "Expected: <(.+?)>.*?But was: <(.+?)>",
"type": "AssertionFailure",
"category": "ValueMismatch",
"description": "Value assertion failed - expected value doesn't match actual value",
"commonCauses": [
"Incorrect expected value in test",
"Logic error in tested code",
"Timing issue (value not yet updated)",
"Floating-point precision error"
],
"solutions": [
{
"condition": "Floating-point comparison",
"fix": "Use Assert.AreEqual(expected, actual, delta) with tolerance",
"example": "Assert.AreEqual(1.0f, result, 0.001f);"
},
{
"condition": "Async operation",
"fix": "Add yield return to wait for operation completion",
"example": "yield return new WaitForSeconds(0.1f);"
},
{
"condition": "Frame-dependent value",
"fix": "Use yield return null to wait for next frame",
"example": "yield return null; // Wait one frame"
}
]
},
{
"pattern": "Expected: not null.*But was: <null>",
"type": "NullReferenceFailure",
"category": "NullValue",
"description": "Expected non-null value but received null",
"commonCauses": [
"Object not instantiated",
"Component not attached",
"Resource not loaded",
"Missing dependency injection"
],
"solutions": [
{
"condition": "GameObject component",
"fix": "Ensure GameObject has required component",
"example": "var component = gameObject.AddComponent<PlayerController>();"
},
{
"condition": "Resource loading",
"fix": "Use Resources.Load or proper asset loading",
"example": "var prefab = Resources.Load<GameObject>(\"Prefabs/Player\");"
},
{
"condition": "Scene object reference",
"fix": "Use GameObject.Find or proper scene setup",
"example": "var player = GameObject.FindGameObjectWithTag(\"Player\");"
}
]
},
{
"pattern": "TimeoutException|Test exceeded time limit",
"type": "TimeoutFailure",
"category": "Performance",
"description": "Test execution exceeded time limit",
"commonCauses": [
"Infinite loop in test or code",
"Deadlock in async operations",
"Slow operation without proper timeout",
"Missing yield in coroutine test"
],
"solutions": [
{
"condition": "Coroutine test",
"fix": "Add [UnityTest] attribute and use yield return",
"example": "[UnityTest] public IEnumerator TestCoroutine() { yield return null; }"
},
{
"condition": "Async operation",
"fix": "Add timeout and proper await/yield",
"example": "yield return new WaitForSecondsRealtime(5f);"
},
{
"condition": "Infinite loop detection",
"fix": "Add loop counter or timeout check",
"example": "int maxIterations = 100; while(condition && maxIterations-- > 0) { }"
}
]
},
{
"pattern": "SetUp.*TearDown.*failed",
"type": "FixtureFailure",
"category": "TestSetup",
"description": "Test setup or teardown method failed",
"commonCauses": [
"Scene loading failure",
"Resource initialization error",
"Missing test dependencies",
"Cleanup error in previous test"
],
"solutions": [
{
"condition": "Scene loading",
"fix": "Use SceneManager.LoadScene in UnitySetUp",
"example": "[UnitySetUp] public IEnumerator SetUp() { yield return SceneManager.LoadSceneAsync(\"TestScene\"); }"
},
{
"condition": "GameObject cleanup",
"fix": "Use Object.DestroyImmediate in TearDown",
"example": "[TearDown] public void TearDown() { Object.DestroyImmediate(testObject); }"
}
]
},
{
"pattern": "MissingReferenceException|The object of type.*has been destroyed",
"type": "DestroyedObjectReference",
"category": "ObjectLifetime",
"description": "Attempted to access a destroyed Unity object",
"commonCauses": [
"Object destroyed before test completes",
"Accessing object after scene unload",
"Component removed during test",
"Improper test cleanup order"
],
"solutions": [
{
"condition": "Test cleanup",
"fix": "Check if object exists before accessing",
"example": "if (testObject != null && testObject) { /* access */ }"
},
{
"condition": "DontDestroyOnLoad objects",
"fix": "Manually destroy objects in TearDown",
"example": "[TearDown] public void TearDown() { Object.DestroyImmediate(GameObject.Find(\"Persistent\")); }"
}
]
},
{
"pattern": "Can't be called from.*main thread",
"type": "ThreadingError",
"category": "Threading",
"description": "Unity API called from wrong thread",
"commonCauses": [
"Async/await without proper context",
"Threading operation accessing Unity API",
"Task.Run accessing GameObject",
"Background thread creating Unity objects"
],
"solutions": [
{
"condition": "Async operations",
"fix": "Use UnityMainThreadDispatcher or yield return",
"example": "yield return new WaitForSeconds(1f); // Keeps on main thread"
},
{
"condition": "Thread synchronization",
"fix": "Queue operations for main thread execution",
"example": "UnityMainThreadDispatcher.Instance().Enqueue(() => { /* Unity API calls */ });"
}
]
}
],
"testModes": {
"EditMode": {
"description": "Tests that run in the Unity Editor without entering Play Mode",
"useCases": [
"Editor scripts and tools testing",
"Non-MonoBehaviour class testing",
"Fast unit tests without scene loading",
"Utility and helper function testing"
],
"limitations": [
"Cannot test MonoBehaviour lifecycle methods (Start, Update, etc.)",
"Cannot test physics or coroutines",
"No scene loading or GameObject instantiation"
],
"attributes": [
"[Test] - Standard NUnit test",
"[TestFixture] - Marks test class",
"[SetUp] - Runs before each test",
"[TearDown] - Runs after each test"
]
},
"PlayMode": {
"description": "Tests that run in Play Mode with full Unity engine functionality",
"useCases": [
"MonoBehaviour lifecycle testing",
"Scene and GameObject testing",
"Physics and collision testing",
"Coroutine and async operation testing"
],
"features": [
"Full Unity engine available",
"Scene loading supported",
"Physics simulation active",
"Coroutines can be used"
],
"attributes": [
"[UnityTest] - Coroutine-based test (returns IEnumerator)",
"[UnitySetUp] - Async setup method",
"[UnityTearDown] - Async teardown method",
"[Test] - Standard synchronous test (also works in PlayMode)"
]
}
},
"bestPractices": [
{
"category": "Test Independence",
"practice": "Each test should be independent and not rely on other tests",
"rationale": "Tests may run in any order and should not affect each other",
"example": "Use [SetUp] to initialize test state, [TearDown] to clean up"
},
{
"category": "Test Naming",
"practice": "Use descriptive test names that explain what is being tested",
"rationale": "Clear names make test failures easier to diagnose",
"example": "TestPlayerTakesDamageWhenHitByEnemy() instead of TestDamage()"
},
{
"category": "Arrange-Act-Assert",
"practice": "Structure tests with clear Arrange, Act, Assert sections",
"rationale": "Makes test logic clear and maintainable",
"example": "// Arrange\nvar player = CreatePlayer();\n// Act\nplayer.TakeDamage(10);\n// Assert\nAssert.AreEqual(90, player.Health);"
},
{
"category": "PlayMode Performance",
"practice": "Use EditMode tests when possible for faster execution",
"rationale": "PlayMode tests are slower due to Unity engine initialization",
"example": "Test pure C# logic in EditMode, reserve PlayMode for Unity-specific features"
},
{
"category": "Async Testing",
"practice": "Use [UnityTest] with IEnumerator for async operations",
"rationale": "Properly handles Unity's frame-based execution",
"example": "[UnityTest] public IEnumerator TestAsync() { yield return new WaitForSeconds(1f); }"
},
{
"category": "Scene Management",
"practice": "Load minimal test scenes for PlayMode tests",
"rationale": "Reduces test execution time and potential side effects",
"example": "Create dedicated empty test scenes with only required objects"
},
{
"category": "Test Categorization",
"practice": "Use [Category] attribute to group related tests",
"rationale": "Enables selective test execution",
"example": "[Test, Category(\"Combat\")] public void TestPlayerAttack() { }"
},
{
"category": "Floating-Point Comparison",
"practice": "Use tolerance when comparing floating-point values",
"rationale": "Floating-point arithmetic is imprecise",
"example": "Assert.AreEqual(expected, actual, 0.001f);"
}
],
"unitySpecificPatterns": {
"coroutineTesting": {
"description": "Testing coroutines requires [UnityTest] attribute",
"example": "[UnityTest]\npublic IEnumerator TestCoroutine()\n{\n var go = new GameObject();\n var component = go.AddComponent<MyComponent>();\n component.StartCoroutine(component.MyCoroutine());\n yield return new WaitForSeconds(1f);\n Assert.IsTrue(component.IsComplete);\n}"
},
"sceneTesting": {
"description": "Loading scenes in tests requires async operations",
"example": "[UnitySetUp]\npublic IEnumerator SetUp()\n{\n yield return SceneManager.LoadSceneAsync(\"TestScene\", LoadSceneMode.Single);\n}"
},
"prefabTesting": {
"description": "Testing prefabs requires instantiation",
"example": "[Test]\npublic void TestPrefab()\n{\n var prefab = Resources.Load<GameObject>(\"Prefabs/Player\");\n var instance = Object.Instantiate(prefab);\n Assert.IsNotNull(instance.GetComponent<PlayerController>());\n Object.DestroyImmediate(instance);\n}"
},
"physicsTesting": {
"description": "Physics tests need time for simulation",
"example": "[UnityTest]\npublic IEnumerator TestPhysics()\n{\n var go = GameObject.CreatePrimitive(PrimitiveType.Sphere);\n var rb = go.AddComponent<Rigidbody>();\n rb.AddForce(Vector3.up * 10f);\n yield return new WaitForFixedUpdate();\n Assert.Greater(rb.velocity.y, 0f);\n}"
}
}
}

279
skills/unity-test-runner/scripts/find-unity-editor.js Normal file
View File

@@ -0,0 +1,279 @@
#!/usr/bin/env node
/**
* Unity Editor Path Finder
*
* Cross-platform script to automatically detect Unity Editor installation paths.
* Supports Windows, macOS, and Linux.
*
* Usage:
* node find-unity-editor.js [--version <version>] [--json]
*
* Options:
* --version <version> Find specific Unity version (e.g., 2021.3.15f1)
* --json Output results as JSON
*
* Output (JSON):
* {
* "found": true,
* "editorPath": "/path/to/Unity",
* "version": "2021.3.15f1",
* "platform": "win32|darwin|linux",
* "allVersions": [...]
* }
*/
const fs = require('fs');
const path = require('path');
// Parse command line arguments
const args = process.argv.slice(2);
const requestedVersion = args.includes('--version')
? args[args.indexOf('--version') + 1]
: null;
const jsonOutput = args.includes('--json');
/**
* Get default Unity installation paths for current platform
*/
function getDefaultUnityPaths() {
const platform = process.platform;
const home = process.env.HOME || process.env.USERPROFILE;
switch (platform) {
case 'win32':
return [
'C:\\Program Files\\Unity\\Hub\\Editor',
'C:\\Program Files\\Unity',
path.join(home, 'AppData', 'Local', 'Unity', 'Hub', 'Editor')
];
case 'darwin':
return [
'/Applications/Unity/Hub/Editor',
'/Applications/Unity',
path.join(home, 'Applications', 'Unity', 'Hub', 'Editor')
];
case 'linux':
return [
path.join(home, 'Unity', 'Hub', 'Editor'),
'/opt/unity',
'/usr/share/unity'
];
default:
return [];
}
}
/**
* Get Unity executable name for current platform
*/
function getUnityExecutableName() {
const platform = process.platform;
switch (platform) {
case 'win32':
return 'Unity.exe';
case 'darwin':
return 'Unity.app/Contents/MacOS/Unity';
case 'linux':
return 'Unity';
default:
return 'Unity';
}
}
/**
* Get Unity executable path from version directory
*/
function getUnityExecutablePath(versionPath) {
const platform = process.platform;
if (platform === 'win32') {
return path.join(versionPath, 'Editor', 'Unity.exe');
} else if (platform === 'darwin') {
return path.join(versionPath, 'Unity.app', 'Contents', 'MacOS', 'Unity');
} else {
return path.join(versionPath, 'Editor', 'Unity');
}
}
/**
* Check if a path contains a valid Unity installation
*/
function isValidUnityInstallation(versionPath) {
return fs.existsSync(getUnityExecutablePath(versionPath));
}
/**
* Parse Unity version string for sorting
* Format: 2021.3.15f1 -> {year: 2021, major: 3, minor: 15, build: 'f', patch: 1}
*/
function parseUnityVersion(versionStr) {
const match = versionStr.match(/(\d+)\.(\d+)\.(\d+)([a-z])(\d+)/);
if (!match) return null;
return {
year: parseInt(match[1]),
major: parseInt(match[2]),
minor: parseInt(match[3]),
build: match[4],
patch: parseInt(match[5]),
full: versionStr
};
}
/**
* Compare two Unity versions
*/
function compareVersions(a, b) {
const vA = parseUnityVersion(a);
const vB = parseUnityVersion(b);
if (!vA || !vB) return 0;
if (vA.year !== vB.year) return vB.year - vA.year;
if (vA.major !== vB.major) return vB.major - vA.major;
if (vA.minor !== vB.minor) return vB.minor - vA.minor;
if (vA.build !== vB.build) return vB.build.localeCompare(vA.build);
return vB.patch - vA.patch;
}
/**
* Scan directory for Unity installations
*/
function scanForUnityVersions(basePath) {
if (!fs.existsSync(basePath)) {
return [];
}
try {
const entries = fs.readdirSync(basePath, { withFileTypes: true });
const versions = [];
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const versionPath = path.join(basePath, entry.name);
// Check if this looks like a Unity version (e.g., 2021.3.15f1)
if (/^\d{4}\.\d+\.\d+[a-z]\d+$/.test(entry.name) && isValidUnityInstallation(versionPath)) {
versions.push({
version: entry.name,
path: versionPath,
executablePath: getUnityExecutablePath(versionPath)
});
}
}
return versions;
} catch (error) {
return [];
}
}
/**
* Find all Unity installations
*/
function findAllUnityInstallations() {
const searchPaths = getDefaultUnityPaths();
const allVersions = [];
for (const searchPath of searchPaths) {
const versions = scanForUnityVersions(searchPath);
allVersions.push(...versions);
}
// Remove duplicates based on version string
const uniqueVersions = allVersions.filter((v, index, self) =>
index === self.findIndex(t => t.version === v.version)
);
// Sort by version (newest first)
uniqueVersions.sort((a, b) => compareVersions(a.version, b.version));
return uniqueVersions;
}
/**
* Find Unity Editor
*/
function findUnityEditor() {
const allVersions = findAllUnityInstallations();
if (allVersions.length === 0) {
return {
found: false,
error: 'No Unity installations found',
platform: process.platform,
searchedPaths: getDefaultUnityPaths()
};
}
// If specific version requested, find it
if (requestedVersion) {
const found = allVersions.find(v => v.version === requestedVersion);
if (found) {
return {
found: true,
editorPath: found.executablePath,
version: found.version,
platform: process.platform,
allVersions: allVersions.map(v => v.version)
};
} else {
return {
found: false,
error: `Unity version ${requestedVersion} not found`,
platform: process.platform,
availableVersions: allVersions.map(v => v.version)
};
}
}
// Return latest version
const latest = allVersions[0];
return {
found: true,
editorPath: latest.executablePath,
version: latest.version,
platform: process.platform,
allVersions: allVersions.map(v => v.version)
};
}
// Main execution
try {
const result = findUnityEditor();
if (jsonOutput) {
console.log(JSON.stringify(result, null, 2));
} else {
if (result.found) {
console.log(`✓ Unity ${result.version} found`);
console.log(` Path: ${result.editorPath}`);
console.log(` Platform: ${result.platform}`);
if (result.allVersions && result.allVersions.length > 1) {
console.log(`\n Other versions available: ${result.allVersions.slice(1).join(', ')}`);
}
} else {
console.error(`✗ ${result.error}`);
if (result.availableVersions && result.availableVersions.length > 0) {
console.error(`\n Available versions: ${result.availableVersions.join(', ')}`);
} else if (result.searchedPaths) {
console.error(`\n Searched paths:`);
result.searchedPaths.forEach(p => console.error(` - ${p}`));
}
process.exit(1);
}
}
} catch (error) {
console.error(`Error: ${error.message}`);
process.exit(1);
}

284
skills/unity-test-runner/scripts/parse-test-results.js Normal file
View File

@@ -0,0 +1,284 @@
#!/usr/bin/env node
/**
* Unity Test Results Parser
*
* Parses Unity Test Framework NUnit XML output and extracts test statistics and failure details.
*
* Usage:
* node parse-test-results.js <path-to-results.xml> [--json]
*
* Options:
* --json Output results as JSON
*
* Output (JSON):
* {
* "summary": {
* "total": 10,
* "passed": 7,
* "failed": 2,
* "skipped": 1,
* "duration": 1.234
* },
* "failures": [
* {
* "name": "TestName",
* "fullName": "Namespace.Class.TestName",
* "message": "Failure message",
* "stackTrace": "Stack trace",
* "file": "Assets/Tests/TestFile.cs",
* "line": 42
* }
* ]
* }
*/
const fs = require('fs');
const path = require('path');
// Parse command line arguments
const args = process.argv.slice(2);
if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
console.log('Usage: node parse-test-results.js <path-to-results.xml> [--json]');
process.exit(args.length === 0 ? 1 : 0);
}
const resultsPath = args[0];
const jsonOutput = args.includes('--json');
/**
* Extract text content from XML tag
*
* Note: This uses regex-based parsing instead of a full XML parser library.
* While regex-based XML parsing is generally not recommended, it's sufficient
* for Unity Test Framework's consistent NUnit XML output format. The patterns
* are designed to be non-greedy and handle common variations (attributes, whitespace).
*
* For production use with arbitrary XML, consider using fast-xml-parser or xml2js.
*/
function extractTagContent(xml, tagName) {
// Non-greedy matching: [\s\S]*? ensures minimal capture between tags
// [^>]* allows for attributes without capturing them (stops at first >)
const regex = new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)<\\/${tagName}>`, 'i');
const match = xml.match(regex);
return match ? match[1].trim() : '';
}
/**
* Extract attribute value from XML tag
*
* Handles attributes with double quotes. Unity NUnit XML consistently uses
* double quotes for attributes, so this simple pattern is reliable.
*/
function extractAttribute(tag, attrName) {
// Escape special regex characters in attribute name
const escapedAttrName = attrName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const regex = new RegExp(`${escapedAttrName}="([^"]*)"`, 'i');
const match = tag.match(regex);
return match ? match[1] : null;
}
/**
* Extract file path and line number from stack trace
*/
function extractFileInfo(stackTrace) {
// Pattern: at Namespace.Class.Method () [0x00000] in /path/to/file.cs:42
// Pattern: at Namespace.Class.Method () in Assets/Tests/TestFile.cs:line 42
const patterns = [
/in (.+\.cs):(\d+)/i,
/in (.+\.cs):line (\d+)/i,
/\[0x[0-9a-f]+\] in (.+\.cs):(\d+)/i
];
for (const pattern of patterns) {
const match = stackTrace.match(pattern);
if (match) {
return {
file: match[1],
line: parseInt(match[2])
};
}
}
return {
file: null,
line: null
};
}
/**
* Parse test-case element
*
* Extracts test metadata from <test-case> XML element using attribute matching.
* All attributes are optional - defaults are provided for missing values.
*/
function parseTestCase(testCaseXml) {
// Extract attributes with fallback defaults
const nameMatch = testCaseXml.match(/name="([^"]*)"/);
const fullNameMatch = testCaseXml.match(/fullname="([^"]*)"/);
const resultMatch = testCaseXml.match(/result="([^"]*)"/);
const durationMatch = testCaseXml.match(/duration="([^"]*)"/);
const testCase = {
name: nameMatch ? nameMatch[1] : 'Unknown',
fullName: fullNameMatch ? fullNameMatch[1] : 'Unknown',
result: resultMatch ? resultMatch[1] : 'Unknown',
duration: durationMatch ? parseFloat(durationMatch[1]) || 0 : 0
};
// Extract failure information if test failed
if (testCase.result === 'Failed') {
const failureXml = extractTagContent(testCaseXml, 'failure');
if (failureXml) {
testCase.message = extractTagContent(failureXml, 'message');
testCase.stackTrace = extractTagContent(failureXml, 'stack-trace');
// Extract file and line from stack trace
if (testCase.stackTrace) {
const fileInfo = extractFileInfo(testCase.stackTrace);
testCase.file = fileInfo.file;
testCase.line = fileInfo.line;
}
}
}
return testCase;
}
/**
* Parse Unity Test Framework XML results
*
* Parses NUnit XML format produced by Unity Test Framework.
* Expects standard Unity test output structure with <test-run> root element.
*
* @param {string} xmlContent - Raw XML content from test results file
* @returns {Object} Parsed test results with summary, failures, and all tests
* @throws {Error} If XML structure is invalid or test-run element is missing
*/
function parseTestResults(xmlContent) {
// Validate XML has test-run root element
const testRunMatch = xmlContent.match(/<test-run[^>]*>/i);
if (!testRunMatch) {
throw new Error('Invalid Unity Test Framework XML: <test-run> element not found. ' +
'Ensure the file is a valid NUnit XML results file from Unity.');
}
const testRunTag = testRunMatch[0];
const summary = {
total: parseInt(extractAttribute(testRunTag, 'total') || '0'),
passed: parseInt(extractAttribute(testRunTag, 'passed') || '0'),
failed: parseInt(extractAttribute(testRunTag, 'failed') || '0'),
skipped: parseInt(extractAttribute(testRunTag, 'skipped') || '0') +
parseInt(extractAttribute(testRunTag, 'inconclusive') || '0'),
duration: parseFloat(extractAttribute(testRunTag, 'duration') || '0')
};
// Extract all test cases using non-greedy matching
// Pattern matches <test-case ...>...</test-case> with minimal capture
// [^>]* stops at first >, [\s\S]*? captures minimal content between tags
const testCaseRegex = /<test-case[^>]*>[\s\S]*?<\/test-case>/gi;
const testCaseMatches = xmlContent.match(testCaseRegex) || [];
const allTests = [];
const failures = [];
for (const testCaseXml of testCaseMatches) {
const testCase = parseTestCase(testCaseXml);
allTests.push(testCase);
if (testCase.result === 'Failed') {
failures.push(testCase);
}
}
return {
summary,
failures,
allTests
};
}
/**
* Format output for console
*/
function formatConsoleOutput(results) {
const { summary, failures } = results;
console.log('\n=== Unity Test Results ===\n');
// Summary
console.log(`Total Tests: ${summary.total}`);
console.log(`✓ Passed: ${summary.passed}`);
if (summary.failed > 0) {
console.log(`✗ Failed: ${summary.failed}`);
}
if (summary.skipped > 0) {
console.log(`⊘ Skipped: ${summary.skipped}`);
}
console.log(`Duration: ${summary.duration.toFixed(3)}s\n`);
// Failures
if (failures.length > 0) {
console.log('=== Failed Tests ===\n');
failures.forEach((failure, index) => {
console.log(`${index + 1}. ${failure.fullName}`);
if (failure.message) {
console.log(` Message: ${failure.message}`);
}
if (failure.file && failure.line) {
console.log(` Location: ${failure.file}:${failure.line}`);
}
if (failure.stackTrace) {
console.log(` Stack Trace:`);
const lines = failure.stackTrace.split('\n').slice(0, 3);
lines.forEach(line => console.log(` ${line.trim()}`));
if (failure.stackTrace.split('\n').length > 3) {
console.log(` ... (truncated)`);
}
}
console.log('');
});
} else {
console.log('✓ All tests passed!\n');
}
}
// Main execution
try {
// Check if file exists
if (!fs.existsSync(resultsPath)) {
console.error(`Error: Test results file not found: ${resultsPath}`);
process.exit(1);
}
// Read and parse XML
const xmlContent = fs.readFileSync(resultsPath, 'utf-8');
const results = parseTestResults(xmlContent);
// Output results
if (jsonOutput) {
console.log(JSON.stringify(results, null, 2));
} else {
formatConsoleOutput(results);
}
// Exit with error code if tests failed
if (results.summary.failed > 0) {
process.exit(1);
}
} catch (error) {
console.error(`Error parsing test results: ${error.message}`);
process.exit(1);
}

73
skills/unity-ui-selector/SKILL.md Normal file
View File

@@ -0,0 +1,73 @@
---
name: Unity UI System Selector
description: Guides selection between UGUI and UI Toolkit for projects. Use when choosing UI framework or migrating UI systems.
---
# Unity UI System Selector
Helps you choose the appropriate UI system for your Unity project and provides implementation guidance for both UGUI and UI Toolkit.
## Two UI Systems
**UGUI (Legacy)** - GameObject-based (2014). Mature, works on all Unity versions, large community. Weaker: Complex UI performance, limited styling, no live reload.
**UI Toolkit (Modern)** - Retained mode, web-inspired UXML/USS (2021.2+). Better performance, live reload, data-binding. Weaker: Requires 2021.2+, smaller community, limited 3D world-space UI.
## Decision Framework
**Use UGUI if:**
- Unity < 2021.2
- Simple UI (menus, HUD)
- 3D world-space UI needed
- Team knows UGUI well / tight deadline
- Legacy project
**Use UI Toolkit if:**
- Unity 2021.2+ and new project (future-proof)
- Complex/data-driven UI (inventory, skill trees)
- Editor tools (inspectors, windows) - **strongly recommended**
- Web dev background (HTML/CSS)
- Large-scale UI (MMO, strategy games)
When in doubt: For new projects on Unity 2021.2+, **UI Toolkit is recommended**.
## Comparison
| Feature | UGUI | UI Toolkit |
|---------|------|-----------|
| **Version** | 4.6+ | 2021.2+ |
| **Performance** | Simple UIs | All UIs |
| **Styling** | Inspector | CSS-like USS |
| **Layout** | Manual/Groups | Flexbox-like |
| **Editor Tools** | Good | Excellent |
| **Runtime UI** | Excellent | Good |
| **3D World UI** | Excellent | Limited |
## Migration
See [migration-guide.md](migration-guide.md) for UGUI → UI Toolkit migration strategy (3-4 months for medium projects).
## UI System Support Matrix
| Unity Version | UGUI | UI Toolkit (Editor) | UI Toolkit (Runtime) |
|--------------|------|-------------------|---------------------|
| 2019.4 LTS | ✅ Full | ✅ Basic | ❌ No |
| 2020.3 LTS | ✅ Full | ✅ Good | ⚠️ Experimental |
| 2021.3 LTS | ✅ Full | ✅ Excellent | ✅ Production |
| 2022.3 LTS+ | ✅ Full | ✅ Primary | ✅ Full |
## When to Use vs Other Components
**Use this Skill when**: Choosing between UGUI and UI Toolkit, understanding UI system trade-offs, or planning UI migration
**Use @unity-scripter agent when**: Implementing UI components, writing custom UI scripts, or converting UI code
**Use @unity-architect agent when**: Designing complex UI architecture, planning UI data flow, or structuring large-scale UI systems
**Use /unity:new-script command when**: Generating Editor scripts with UI Toolkit or UGUI templates
## Related Skills
- **unity-uitoolkit**: Assists with UI Toolkit implementation (UXML, USS, VisualElement API)
- **unity-template-generator**: Generates Editor scripts using selected UI system
- **unity-script-validator**: Validates UI code patterns

86
skills/unity-uitoolkit/SKILL.md Normal file
View File

@@ -0,0 +1,86 @@
---
name: Unity UI Toolkit
description: Assists with Unity UI Toolkit development - UXML structure, USS styling, C# VisualElement manipulation, data binding, and custom controls. Use when implementing UI Toolkit interfaces.
allowed-tools: Read, Write, Glob
---
# Unity UI Toolkit
Assists with Unity UI Toolkit development including UXML markup, USS styling, C# VisualElement API, and modern UI patterns.
## What This Skill Helps With
### UXML Structure
- Proper element hierarchy and naming conventions
- Common controls: TextField, Button, Toggle, Slider, ObjectField, ListView
- Layout containers: VisualElement, ScrollView, Foldout, TwoPaneSplitView
- Data-driven UI with templates and bindings
### USS Styling
- Class-based styling and selectors
- Flexbox layout (flex-direction, justify-content, align-items)
- USS variables and dark theme optimization
- Pseudo-classes (:hover, :active, :disabled)
- Transitions and animations
### C# VisualElement API
- Query API: `rootElement.Q<Button>("my-button")`
- Event handling: `.clicked +=` and `.RegisterValueChangedCallback()`
- Dynamic UI creation with constructors
- Data binding with `Bind()` and `SerializedObject`
### Best Practices
- UXML for structure, USS for styling, C# for logic
- Name elements for Query API access
- Use classes for styling, not inline styles
- Cache VisualElement references in fields
- Proper event cleanup in `OnDestroy()`
## Common Patterns
**Editor Window Setup:**
```csharp
public void CreateGUI() {
var visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("path/to.uxml");
visualTree.CloneTree(rootVisualElement);
var button = rootVisualElement.Q<Button>("my-button");
button.clicked += OnButtonClick;
}
```
**USS Class Toggle:**
```csharp
element.AddToClassList("active");
element.RemoveFromClassList("active");
element.ToggleInClassList("active");
```
**Data Binding:**
```csharp
var so = new SerializedObject(target);
rootVisualElement.Bind(so);
```
## Unity Version Requirements
- **Unity 2021.2+** for runtime UI Toolkit
- **Unity 2019.4+** for editor-only UI Toolkit (limited features)
See [ui-toolkit-reference.md](ui-toolkit-reference.md) for complete API documentation.
## When to Use vs Other Components
**Use this Skill when**: Building UI Toolkit interfaces, writing UXML/USS, or manipulating VisualElements in C#
**Use unity-ui-selector skill when**: Choosing between UGUI and UI Toolkit for a project
**Use @unity-scripter agent when**: Implementing complex UI logic or custom VisualElement controls
**Use EditorScriptUIToolkit templates when**: Generating new UI Toolkit editor windows with UXML/USS files
## Related Skills
- **unity-ui-selector**: Helps choose between UGUI and UI Toolkit
- **unity-template-generator**: Generates UI Toolkit editor script templates
- **unity-script-validator**: Validates UI Toolkit code patterns

203
skills/unity-uitoolkit/ui-toolkit-reference.md Normal file
View File

@@ -0,0 +1,203 @@
# UI Toolkit Quick Reference
## Common VisualElement Types
### Input Controls
- `TextField` - Single/multi-line text input
- `IntegerField`, `FloatField`, `Vector3Field` - Numeric inputs
- `Toggle` - Boolean checkbox
- `Button` - Clickable button
- `Slider` - Value slider with optional input field
- `EnumField` - Dropdown for enum values
- `ObjectField` - Unity Object reference picker
### Layout Containers
- `VisualElement` - Generic container (like `<div>`)
- `ScrollView` - Scrollable area
- `Foldout` - Collapsible section
- `TwoPaneSplitView` - Resizable split panel
- `ListView` - Data-driven list with virtualization
### Display Elements
- `Label` - Text display
- `Image` - Sprite/Texture display
- `HelpBox` - Info/Warning/Error message box
- `ProgressBar` - Progress indicator
## USS Flexbox Layout
```css
.container {
flex-direction: row; /* or column */
justify-content: flex-start; /* flex-end, center, space-between */
align-items: stretch; /* flex-start, flex-end, center */
flex-grow: 1;
flex-shrink: 0;
}
```
## USS Common Properties
```css
/* Spacing */
margin: 10px;
padding: 5px 10px;
/* Sizing */
width: 200px;
height: 100px;
min-width: 50px;
max-height: 300px;
/* Background */
background-color: rgb(50, 50, 50);
background-image: url('path/to/image.png');
/* Border */
border-width: 1px;
border-color: rgba(255, 255, 255, 0.2);
border-radius: 4px;
/* Text */
color: rgb(200, 200, 200);
font-size: 14px;
-unity-font-style: bold; /* or italic */
-unity-text-align: middle-center;
```
## Query API Examples
```csharp
// By name (must set name in UXML)
var button = root.Q<Button>("my-button");
// By class
var items = root.Query<VisualElement>(className: "item").ToList();
// First match
var firstLabel = root.Q<Label>();
// All matches
var allButtons = root.Query<Button>().ToList();
// Complex query
var activeItems = root.Query<VisualElement>()
.Where(e => e.ClassListContains("active"))
.ToList();
```
## Event Handling
```csharp
// Button click
button.clicked += () => Debug.Log("Clicked!");
// Value change
textField.RegisterValueChangedCallback(evt => {
Debug.Log($"Changed: {evt.previousValue} -> {evt.newValue}");
});
// Mouse events
element.RegisterCallback<MouseDownEvent>(evt => {
Debug.Log($"Mouse down at {evt.localMousePosition}");
});
// Cleanup
void OnDestroy() {
button.clicked -= OnButtonClick;
}
```
## Data Binding
```csharp
// Bind to SerializedObject
var so = new SerializedObject(targetObject);
rootVisualElement.Bind(so);
// Manual binding
var property = so.FindProperty("fieldName");
var field = new PropertyField(property);
field.BindProperty(property);
```
## Custom VisualElement
```csharp
public class CustomElement : VisualElement
{
public new class UxmlFactory : UxmlFactory<CustomElement, UxmlTraits> { }
public new class UxmlTraits : VisualElement.UxmlTraits
{
UxmlStringAttribute customAttribute = new UxmlStringAttribute
{ name = "custom-value" };
public override void Init(VisualElement ve, IUxmlAttributes bag,
CreationContext cc)
{
base.Init(ve, bag, cc);
((CustomElement)ve).customValue = customAttribute.GetValueFromBag(bag, cc);
}
}
private string customValue;
public CustomElement()
{
AddToClassList("custom-element");
}
}
```
## Performance Tips
1. **Use USS classes** instead of inline styles
2. **Cache VisualElement references** instead of repeated queries
3. **Use ListView** for large lists (virtualized)
4. **Avoid excessive rebuilds** - update only changed elements
5. **Use USS variables** for maintainable themes
6. **Minimize UXML nesting** for better performance
## Common Pitfalls
❌ **Querying before CreateGUI finishes**
```csharp
// Wrong
void OnEnable() {
var button = rootVisualElement.Q<Button>(); // null!
}
// Correct
public void CreateGUI() {
visualTree.CloneTree(rootVisualElement);
var button = rootVisualElement.Q<Button>(); // works!
}
```
❌ **Forgetting to name elements**
```xml
<!-- Wrong: Can't query by name -->
<ui:Button text="Click" />
<!-- Correct -->
<ui:Button name="my-button" text="Click" />
```
❌ **Not cleaning up events**
```csharp
// Memory leak!
button.clicked += OnClick;
// Correct
void OnDestroy() {
button.clicked -= OnClick;
}
```
## Resources
- Unity Manual: UI Toolkit
- Unity Scripting API: UnityEngine.UIElements
- Unity Forum: UI Toolkit section
- Sample Projects: UI Toolkit samples on GitHub