Blender Addon Template

A GitHub template repository for creating Blender addons with automated release packaging.

Getting Started

1. Use This Template

Click the "Use this template" button on GitHub to create a new repository based on this template.

2. Configure Your Addon

Rename the Addon Folder

Rename the folder from addons/BlenderTemplate to addons/<<PLUGIN_NAME>>:

mv addons/BlenderTemplate addons/YourPluginName

Replace YourPluginName with your actual plugin name (e.g., MyAwesomeAddon).

Update the GitHub Workflow

Edit .github/workflows/release.yml and change the PLUGIN_NAME environment variable to match your plugin folder name:

env:
  PLUGIN_NAME: YourPluginName  # Change this to match your addon folder name

Important: The PLUGIN_NAME must exactly match the folder name in the addons/ directory.

Update the Addon Metadata

Edit addons/<<PLUGIN_NAME>>/__init__.py and update the bl_info dictionary with your addon's information:

bl_info = {
    "name": "Your Addon Name",
    "author": "Your Name",
    "version": (1, 0, 0),
    "blender": (2, 80, 0),
    "location": "View3D > Sidebar > Your Tab",
    "description": "Description of your addon",
    "category": "Object",
}

Development Setup

Installing the Addon for Development

To develop your addon without manually copying files to Blender's addon directory, you can add a script path that points directly to your workspace:

1. Open Blender
2. Go to Edit > Preferences (or Blender > Preferences on macOS)
3. Navigate to File Paths
4. Scroll down to the Script Directories section
5. Click the + button to add a new path
6. Browse to and select your repository's root directory (e.g., /Users/yourname/Developer/BlenderTemplate)
7. Click OK to save

Now Blender will scan the addons/ subfolder in your repository and make your addon available.

Enabling Your Addon

After adding the script path:

1. Go to Edit > Preferences > Add-ons
2. Search for your addon name
3. Enable it by checking the checkbox
4. Click Save Preferences to enable it on startup

Development Workflow

When developing:

1. Make changes to your addon code
2. In Blender, go to Edit > Preferences > Add-ons
3. Find your addon and click the Refresh button (or press F8 to reload addons)
4. Alternatively, restart Blender to reload all scripts

Tip: For faster iteration, you can reload your addon using Blender's built-in script reloading or by toggling the addon off and on in the preferences.

Releasing Your Addon

Creating a Release

1. Commit and push your changes to GitHub
2. Create a new tag with semantic versioning:

   git tag v1.0.0
   git push origin v1.0.0

3. Go to your GitHub repository and create a new release from the tag
4. The GitHub Actions workflow will automatically:
   • Bundle your addon into a zip file
   • Attach it to the release as YourPluginName-1.0.0.zip

Installing a Released Addon

Users can install your addon by:

1. Downloading the .zip file from the GitHub release
2. Opening Blender
3. Going to Edit > Preferences > Add-ons
4. Clicking Install and selecting the downloaded .zip file
5. Enabling the addon from the list

Project Structure

.
├── .github/
│   └── workflows/
│       └── release.yml          # Automated release workflow
├── addons/
│   └── <<PLUGIN_NAME>>/        # Your addon folder (rename this!)
│       └── __init__.py          # Addon entry point and metadata
└── README.md

Resources

• Blender Python API Documentation
• Blender Addon Tutorial
• Blender Add-on Guidelines