feat: Add Complete Visual MAXScript AI Agent Desktop Application

.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# MAXScript AI Agent specific
+*.ms.bak
+test_output/
+generated_scripts/

README_MAXSCRIPT_AGENT.md

@@ -0,0 +1,277 @@
+# MAXScript AI Agent
+
+An AI agent specialized in writing MAXScript code for Autodesk 3ds Max. This agent provides comprehensive MAXScript code generation, debugging, and best practices for 3ds Max versions 2018-2024.
+
+## Features
+
+### Core Functionality
+- **Code Generation**: Generate MAXScript code for common 3ds Max operations
+- **Syntax Validation**: Validate MAXScript syntax and identify errors
+- **Code Debugging**: Debug existing MAXScript code with intelligent suggestions
+- **Best Practices**: Enforce MAXScript coding standards and best practices
+- **Concept Explanation**: Explain MAXScript concepts and usage patterns
+
+### Technical Capabilities
+- Support for MAXScript syntax across 3ds Max versions 2018-2024
+- Proper variable declarations, function definitions, and object manipulation
+- Handle all MAXScript data types (arrays, strings, numbers, objects, nodes)
+- Scene node traversal and selection methods
+- Error handling and user feedback integration
+
+### Use Cases
+- **Modeling Automation**: Scripts for repetitive modeling tasks
+- **Animation Tools**: Keyframe manipulation and animation automation
+- **Rendering Utilities**: Batch rendering and camera management
+- **Scene Management**: Object organization and scene setup
+- **Custom UI Creation**: Rollouts, dialogs, and tool interfaces
+- **Workflow Automation**: Batch processing and file operations
+
+## Installation
+
+1. Clone or download the MAXScript AI Agent files
+2. Ensure Python 3.7+ is installed
+3. No additional dependencies required - uses only Python standard library
+
+## Usage
+
+### Command Line Interface
+
+#### Generate MAXScript Code
+```bash
+# Generate a function
+python main.py generate "Create 10 boxes in a row" --type function
+
+# Generate a UI rollout
+python main.py generate "Object selection tool" --type rollout --ui
+
+# Generate a macro
+python main.py generate "Hide selected objects" --type macro
+
+# Generate with specific options
+python main.py generate "Animate rotation" --type function --version 2023 --output my_script.ms
+```
+
+#### Get Code Templates
+```bash
+# List all modeling templates
+python main.py template modeling
+
+# Get specific template
+python main.py template modeling create_primitive_array
+
+# List all available categories
+python main.py template animation
+python main.py template ui
+python main.py template utility
+python main.py template workflow
+python main.py template rendering
+```
+
+#### Validate and Debug Scripts
+```bash
+# Validate syntax
+python main.py validate my_script.ms
+
+# Debug with error message
+python main.py debug my_script.ms --error "undefined variable"
+```
+
+#### Search Functions and Get Help
+```bash
+# Search for functions
+python main.py search "selection"
+
+# Explain concepts
+python main.py explain rollout
+python main.py explain struct
+
+# Show best practices
+python main.py practices
+```
+
+#### Interactive Mode
+```bash
+python main.py interactive
+```
+
+In interactive mode, you can use these commands:
+- `generate <description>` - Generate MAXScript code
+- `explain <concept>` - Explain MAXScript concept
+- `search <keyword>` - Search functions
+- `practices` - Show best practices
+- `help` - Show available commands
+- `quit` - Exit
+
+### Python API
+
+```python
+from maxscript_agent import MAXScriptAgent, ScriptRequest, ScriptType, MaxVersion
+
+# Create agent
+agent = MAXScriptAgent()
+
+# Create request
+request = ScriptRequest(
+    description="Create a spiral staircase",
+    script_type=ScriptType.FUNCTION,
+    max_version=MaxVersion.MAX_2024,
+    include_ui=False,
+    include_error_handling=True,
+    include_comments=True
+)
+
+# Generate code
+code = agent.generate_script(request)
+print(code)
+
+# Validate syntax
+is_valid, errors = agent.validate_syntax(code)
+
+# Debug code
+debug_info = agent.debug_script(code, "error message")
+
+# Explain concepts
+explanation = agent.explain_concept("rollout")
+```
+
+## Script Types
+
+The agent can generate different types of MAXScript code:
+
+### Function
+Basic functions for reusable operations
+```maxscript
+fn myFunction param1 param2 =
+(
+    -- Function body
+    return result
+)
+```
+
+### Rollout
+UI dialogs and panels
+```maxscript
+rollout myRollout "My Tool" width:300 height:200
+(
+    button btn1 "Execute"
+    on btn1 pressed do (...)
+)
+```
+
+### Macro
+Toolbar buttons and menu items
+```maxscript
+macroScript MyTool category:"Custom Tools"
+(
+    on execute do (...)
+)
+```
+
+### Struct
+Object-oriented data structures
+```maxscript
+struct myStruct
+(
+    property1 = "",
+    fn method1 = (...)
+)
+```
+
+### Utility
+Complete utility scripts with optional UI
+
+### Batch
+Batch processing scripts for multiple files
+
+## Examples
+
+The `examples/` directory contains comprehensive examples:
+
+### Modeling Examples (`examples/modeling_examples.ms`)
+- Create object grids and arrays
+- Distribute objects along curves
+- Build spiral staircases
+- Randomize object properties
+- Create buildings from footprints
+- Mirror objects across planes
+- Generate parametric fences
+
+### Animation Examples (`examples/animation_examples.ms`)
+- Animate object rotation and movement
+- Create bouncing ball animations
+- Animate objects along paths
+- Generate wave animations
+- Camera orbit animations
+- Visibility fade effects
+- Pendulum animations
+- Scale pulse effects
+- Batch keyframe operations
+
+## Knowledge Base
+
+The agent includes comprehensive knowledge of:
+
+### Built-in Functions
+- Scene management (select, hide, delete, etc.)
+- Object creation (box, sphere, cylinder, etc.)
+- Animation (animate, keyframes, controllers)
+- File operations (load, save, merge, export)
+- Utilities (print, format, messageBox)
+- Array and string operations
+- Math functions and coordinate systems
+
+### Object Hierarchy
+- Geometry primitives
+- Shapes and splines
+- Lights and cameras
+- Helpers and space warps
+- Particle systems
+
+### Common Patterns
+- Object iteration and selection
+- Error handling with try/catch
+- File I/O operations
+- UI creation with rollouts
+- Animation keyframe setup
+- Material assignment
+
+### Version Features
+- Version-specific functionality for 3ds Max 2018-2024
+- Compatibility considerations
+- New features and improvements
+
+## Best Practices
+
+The agent enforces these MAXScript best practices:
+
+1. **Error Handling**: Always use try/catch blocks for robust code
+2. **Naming**: Use meaningful variable and function names
+3. **Comments**: Document code thoroughly
+4. **Validation**: Check for object existence before accessing properties
+5. **Selection**: Use clearSelection() before selecting objects
+6. **Input Validation**: Validate user input in UI scripts
+7. **Undo Support**: Use undo blocks for scene-modifying operations
+8. **Clarity**: Prefer explicit iteration over shorthand
+9. **Batch Operations**: Use quiet:true for file operations
+10. **Testing**: Test scripts on simple scenes first
+
+## Contributing
+
+To extend the MAXScript AI Agent:
+
+1. **Add Templates**: Extend `maxscript_templates.py` with new code templates
+2. **Expand Knowledge**: Add functions and classes to `maxscript_knowledge.py`
+3. **Improve Generation**: Enhance the generation logic in `maxscript_agent.py`
+4. **Add Examples**: Create new example scripts in the `examples/` directory
+
+## License
+
+This project uses the same license as the parent repository.
+
+## Support
+
+For questions, issues, or feature requests related to the MAXScript AI Agent, please refer to the main repository documentation or create an issue describing your specific MAXScript needs.
+
+---
+
+**Note**: This AI agent is designed to generate MAXScript code based on descriptions and patterns. Always test generated scripts in a safe environment before using them on important projects. The agent provides a starting point and best practices, but may require customization for specific use cases.