create/docs/examples/example-addon/README.md

Example Addon Template

A minimal but complete Kindred Create addon that demonstrates all major SDK integration points. Copy this directory into mods/, rename it, and start building.

File Structure

example-addon/
├── package.xml              Addon manifest with <kindred> extensions
├── Init.py                  Console-mode bootstrap (runs in all modes)
├── InitGui.py               GUI bootstrap — deferred registration
└── example_addon/
    ├── __init__.py           Python package marker
    ├── commands.py           FreeCAD command via kindred_sdk.register_command()
    └── panel.py              Dock panel widget factory

What This Template Demonstrates

Feature	File	SDK function
Addon manifest with version bounds and dependencies	package.xml	—
Console bootstrap	Init.py	—
Deferred GUI initialization with QTimer.singleShot	InitGui.py	—
Command registration	commands.py	kindred_sdk.register_command()
Injecting commands into existing contexts	InitGui.py	kindred_sdk.inject_commands()
Dock panel registration	InitGui.py, panel.py	kindred_sdk.register_dock_panel()
Context lifecycle hooks	InitGui.py	kindred_sdk.on_context_enter()
Event bus subscription	InitGui.py	kindred_sdk.on()

Installation (for testing)

1. Copy or symlink this directory into the mods/ folder at the repository root:

   cp -r docs/examples/example-addon mods/example-addon
   

2. Launch Kindred Create:

   pixi run freecad
   

3. Open the Python console (View > Panels > Python console) and verify:

   example-addon: console init
   

4. The "Example Panel" dock widget should appear on the right after ~2 seconds.

5. To test the command, create a Part Design Body and look for "Hello World" in the Part Design toolbar.

Customizing

1. Rename — change example-addon and example_addon to your addon's name in all files
2. Update package.xml — set your name, description, repository URL, and load priority
3. Add commands — create more functions in commands.py and register them
4. Add contexts — use kindred_sdk.register_context() for custom editing modes
5. Add overlays — use kindred_sdk.register_overlay() for conditional toolbars
6. Theme colors — use kindred_sdk.get_theme_tokens() for Catppuccin Mocha palette access

Common Pitfalls

• Missing <workbench> tag — InitGui.py will not be loaded without it, even if you don't register a workbench
• Import at module level — avoid importing kindred_sdk or PySide6 at the top of InitGui.py; use deferred imports inside functions to avoid load-order issues
• Blocking startup — keep each QTimer.singleShot callback fast; do heavy work in background threads
• Forgetting <dependency>sdk</dependency> — your addon may load before the SDK if you omit this

Further Reading

• Writing an Addon — full tutorial
• Package.xml Schema — manifest reference
• KCSDK Python API — complete API reference