MechanicsAssistant is a commercial-grade Unity Editor plugin that generates game mechanics from natural language descriptions using AI. Simply describe what you want ("Jump mechanic", "Dash ability"), and the plugin generates production-ready C# code, validates it, and attaches it to selected GameObjects.
Key Features:
- 🤖 AI-Powered Generation - Uses OpenAI GPT-4 or Anthropic Claude models
- ✅ Automatic Validation - Syntax checking, best practices enforcement
- 🎯 Smart Categorization - Organizes code by mechanic type (Movement, Physics, Interaction)
- 🔌 Extensibility - 7-stage hook system for custom validation, monitoring, and integration
- ⚡ Production-Ready - Retry logic, error recovery, comprehensive error messages
- 🧪 Fully Tested - 180+ unit and integration tests covering all functionality
- Unity 2020.3 or later
- Net Framework 4.7.1 or higher (for HttpClient support)
-
Copy Plugin Files
Assets/Editor/MechanicsAssistant/ -
Obtain API Key
- OpenAI: Sign up at platform.openai.com and create an API key
- Anthropic: Sign up at console.anthropic.com and create an API key
-
Configure in Unity
- Open:
Windows → MechanicsAssistant → Configuration - Select your LLM provider (OpenAI or Anthropic)
- Enter your API key (stored securely in Windows Credential Manager)
- Open:
- In the Scene hierarchy, select 1+ GameObjects to attach the mechanic to
- Menu:
Window → AI → MechanicsAssistant
- Type a natural language description:
- "Jump mechanic that responds to spacebar with 10 unit height"
- "Dash ability with 50 unit range and 0.5 second cooldown"
- "Wall slide mechanic that reduces gravity while touching walls"
- Click Generate
- Wait for code generation and attachment (typically 5-15 seconds)
- Code successfully generated and attached?
- ✅ Success: Script appears in Inspector, ready to use
⚠️ Partial: Some targets already had the script- ❌ Failed: Check error message for details (see Troubleshooting)
- Validation - Verify selection and API key
- API Key Retrieval - Load stored credentials
- Context Building - Gather scene information
- Prompt Enrichment - Build LLM request with context
- LLM Call - Query AI model (with retry/timeout)
- Code Extraction - Parse code from markdown
- Syntax Validation - Check C# correctness
- Class Detection - Extract class name
- Categorization - Organization (Movement/Physics/Interaction)
- File Saving - Write to Assets/Generated/
- Compilation - Allow Unity to compile
- Attachment - Add component to GameObjects
- ILLMProvider: Abstract interface for AI models
- OpenAIProvider: GPT-4 implementation (with retry/timeout)
- AnthropicProvider: Claude model implementation
- CodeValidator: Syntax checking and best-practice enforcement
- CodeSaver: File I/O with atomic writes
- CategoryDetector: Mechanic classification
- UndoManager: Action history with undo support
Extensible callback points for custom logic:
- PreGeneration: Early validation (can reject)
- PreContext: Inject context data
- PostCodeExtraction: React to extracted code
- PostValidation: React to validation results
- PostCategory: React to categorization
- PreAttachment: Final validation before mutation
- PostComplete: Logging and integration
- gpt-4o (recommended)
- gpt-4-turbo
- gpt-4
- claude-3-5-sonnet (recommended)
- claude-opus-4-1
- claude-haiku
- Requires Internet: API calls to external LLM providers
- Rate Limits: Subject to provider's rate limiting (typically 20-100 req/min)
- Token Costs: Each generation costs ~0.01-0.10 USD depending on model
- Code Quality: Generated code may need minor adjustments
- No Networking Code: Won't generate multiplayer-specific mechanics
- Max Tokens: Limited to 2000 tokens per response (~600-800 lines of code)
- Generation Time: 5-20 seconds (depends on model and network)
- Retry Logic: 3 attempts with exponential backoff (1s, 2s, 4s)
- Timeout: 30 seconds default (configurable)
- File Operations: <100ms
- UI Responsiveness: Non-blocking async operations
- Memory: ~10MB for plugin + LLM context
# In Unity Test Runner:
Window → Test Runner → PlayMode/EditMode
# Or run via command line:
unity -projectPath . -runTests -testPlatform editmode- 180+ tests across all components
- Unit tests: Individual service validation
- Integration tests: Full pipeline workflows
- Error scenarios: Network, timeout, validation failures
- Hook tests: Extension point validation
"API key not configured"
- Open configuration window
- Enter valid API key from your provider
"Generation timeout (>30s)"
- Check internet connection
- Provider may be rate-limiting; try again in 1 minute
- Consider using faster model (claude-haiku or gpt-4-turbo)
"Code validation failed"
- Generated code may have syntax errors
- Try more specific prompt ("Jump mechanic with Input.GetKeyDown(KeyCode.Space)")
- Check error message for specific validation failure
"Script already attached"
- GameObject already has a script with chosen class name
- Rename in Inspector or generate with different name
"File save failed"
- Check disk space
- Verify write permissions on Assets folder
- Try with shorter class name
See ERROR_HANDLING_GUIDE.md for detailed troubleshooting.
- HOOKS_GUIDE.md - How to implement custom hooks
- IMPLEMENTATION_GUIDE.md - How to extend the system
- ERROR_HANDLING_GUIDE.md - Troubleshooting and error reference
- TESTING_GUIDE.md - Testing and contribution guidelines
- Unity 2020.3 or later
- .NET Framework 4.7.1+
- Internet connection for API calls
- Visual Studio 2019+
- NUnit test framework
- Moq mocking library
MIT License - See LICENSE file for details
For issues, feature requests, or questions:
- Check Troubleshooting section
- Review error message details
- Check logs in
Consolewindow - Consult TESTING_GUIDE.md for diagnostic steps
- Initial release
- OpenAI and Anthropic provider support
- Hook extensibility system
- Comprehensive error handling and retry logic
- Full test coverage
Created with ❤️ for game developers