Integration Guide

A drop-in module for Blender addon developers to automatically check for updates using a centralized API system.

Features

  • ✅ Zero Configuration: Automatically reads your addon ID and version from blender_manifest.toml
  • ✅ Session-Based Checking: Checks once per Blender session (not on every startup)
  • ✅ Panel Integration: Clean UI for preferences and panels
  • ✅ Optional Viewport Overlays: Gizmo-based notifications (disabled by default)
  • ✅ Smart Manifest Finding: Searches parent directories to find your manifest
  • ✅ Multi-Addon Safe: Dynamic class generation prevents conflicts

Quick Start

1. Copy the Module

downloadaddon_update_checker.py

Copy it into your add-on directory. You can place it:

  • In the root: my_addon/addon_update_checker.py
  • In a subfolder: my_addon/modules/addon_update_checker.py
  • In any subfolder up to 3 levels deep

The module will automatically search parent directories to find your blender_manifest.toml.

2. Basic Integration

In your addon's __init__.py:

Python
from . import addon_update_checker

def register():
    # Your registration code here
    # ...
    
    # Register update checker (must be last)
    addon_update_checker.register()

def unregister():
    # Unregister update checker (must be first)
    addon_update_checker.unregister()
    
    # Your unregistration code here
    # ...

That's it! The module will read your addon ID and version, check for updates once per session, and store notification data.

UI Integration

Preferences Panel (Recommended)

Add update checking UI to your addon preferences:

Python
from . import addon_update_checker

class MyAddonPreferences(bpy.types.AddonPreferences, 
                         addon_update_checker.AddonUpdateCheckerProperties):
    bl_idname = __package__

    # Your existing preferences
    my_setting: bpy.props.BoolProperty(name="My Setting")
    
    def draw(self, context):
        layout = self.layout
        
        # Your existing preference UI
        layout.prop(self, "my_setting")
        
        # Add update checker UI
        layout.separator()
        addon_update_checker.draw_update_section_for_prefs(layout, context)

Key Points:

  • Inherit from AddonUpdateCheckerProperties mixin
  • This adds the auc_use_gizmo_notifications property automatically
  • Call draw_update_section_for_prefs() in your draw method

Panel Integration (Optional)

Show update notifications in your addon panels:

Python
class MY_PT_MainPanel(bpy.types.Panel):
    bl_label = "My Addon"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "My Addon"
    
    def draw(self, context):
        layout = self.layout
        
        # Show update notification (only appears if update available)
        addon_update_checker.draw_update_section_for_panel(layout, context)
        
        # Your regular panel UI
        layout.operator("my.operator")

Advanced Usage

Custom Addon ID

def register():
    addon_update_checker.register(addon_id="my-custom-addon-id")

Manual Parent Addon Name

def register():
    addon_update_checker.register(parent_addon_name="my_addon_name")

Viewport Gizmo Notifications

By default, gizmo notifications are disabled. Users can enable them in preferences. It is recommended to guide users to check preferences or panels instead of enabling gizmos to avoid viewport clutter.

Best Practices

  • ✅ Always inherit from AddonUpdateCheckerProperties in your preference class
  • ✅ Register update checker last
  • ✅ Unregister update checker first
  • ✅ Use panel notifications as primary method