2025-03-11 Design Session: Extensions

Meetings
1

Design Session: Extensions

Attendees:

  • Dalai Felinto
  • Francesco Siddi
  • Pablo Vazquez

Design session about the onboarding experience for new extension contributors.

User Story

This is a user story map of going over the steps about creating an extension.

image
image3242×1592 351 KB

Potential areas of improvements or pain-points:

Before publishing

  • “Open Template from Blender”
    • At the moment the add-on example (add object) is disconnected from the process of creating an extension.
    • The user is left on their own the moment they need to pack the add-on as an extension.
  • The process of starting to test an extension (or add-on) is really painful
    • Users have to either find which folders to create and sym-link their extension; or install a dummy extension from disk just to have it.

Proposal:

Low hanging fruit: Rename/Remove the Addon Add Object template.

Good to have: Add syntax highlight for TOML (a good first issue)

Must have: New operator to create extension from Blender

  • Dialog with the following options:
    • Folder
    • :ballot_box_with_check: Install Extension [tooltip: Creates a symlink SYSTEM repository and enables the add-on]
    • Manifest Fields
    • Placeholders
      • Preferences
      • Keymap
      • Menu
      • Operator
      • Panel
      • Pre-render hook
  • Create files in folder.
  • Multi-file from the get-go.
  • Creates a README pointing to the latest documentation.
  • Open preferences with the extension pre-filtered.

Future: Invite a influencer to create a video-tutorial to be hosted on blender.org.

During Publishing

  • Create Draft
    • Chicken-and-egg: You need have an extension to upload, to even start creating an extension.
    • If you don’t know how to create an extension, you need to find the information elsewhere.
    • The relation between creating a draft, and sending for review is not clear to some users.

Proposal:

  • Website: improve “Create extension” page with options for converting and existing add-on, creating a new one from scratch.
  • Website: improve the comment/change status workflow. Limit the amount of options available and turn them into buttons.
  • Website: on extension save, redirect to “review” page instead of versions list
4 Likes
2

It’s hard to get context from post its with random coloured dots on them, but there is one specific one that causes me great concern : symlinking the addons folder is very dangerous and we shouldn’t be advertising it as a recommend workflow.

2 Likes
3

Although operators and tutorials for helping start the development is very nice and good idea, from my experience on the platform, it’s not really a stopping issue for users. Creating first draft is something everyone manages, but after that, fixing stuff or implementing things correctly is big hurdle.

  • Around half of the extensions that are requested to make changes never come back with updates.
  • Developers struggle to understand what is asked of them and often takes multiple rounds of review to get it right.
  • Developers depend on AI language models to fix issues (that are mostly introduced by AI in the first place), and what makes matters worse is that AI models are behind on Blenders API.
  • Developers use helper tools, like Serpens add-on to create extensions, which creates numerous small problems and bloats in the code that they’re often not capable to fix themselves.
  • In most of the cases, developers have clear idea of what they want to achieve, but don’t know how to correctly approach the issue, and they need to be hand-held during updates

As it is now, around half of my time is spent on educating, instead of reviewing.
Main problem, as I see it, is that examples we provide end with creating simple add-on, simple panel and simple operator, and users can’t manage to find their way beyond that. Even knowing how to read API documentation isn’t something familiar for new developers.

I don’t mind teaching stuff, I like it, but it’s not making a difference in big picture unless it’s systemized. There needs to be place where new developers (and asset creators) can learn from humanly understandable examples. For example, I have to keep pointing people to one of my add-ons when I want them to understand some concept, or to see example of the code. I’ve also been told by many that they read reviews of other approved add-ons to see what we might ask them.

To solve this issue I think we need to have one central space for learning, and sharing knowledge. I will make ticket for this proposal on projects, but as I envision it extensions platform should have very simple blog space: just markdown pages inside categories, with authors. In this space there should be pages that teach common, or even rare examples.

I know it’s beyond the scope of this design session, and I will raise this topic separately. Just wanted to share where I see issues from actual developers I deal with on extensions platform.

4 Likes
4

Being less strict on code review would also simplify things.
As long as plugins are not dangerous for the user computer, the creator should be able to publish it if it’s working.

Blender extensively use the word Freedom, yet… this Freedom is tainted in a lot of rules and appeal to organizers authority

2 Likes
5

Of course, the functionality is the most important thing. On the other hand, whoever publishes has to maintain the code as well. And people who use the extension usually expect it to work in the future as well. If someone doesn’t have the necessary knowledge to maintain the code, they shouldn’t publish the extension in the first place (at least not on that platform).

Edit: I am sure not everything is perfect. That still doesn’t mean all the quality standards should be thrown over the board.

This has nothing to do with that. Everyone has the freedom to publish any kind of extension they want. But there have to be some quality standards in place for the official platforms.
Everyone has the freedom to modify Blender as well, but that doesn’t give them the ability to push those changes into the official Blender version.
They are properly using their authority to ensure a basic quality standard.

7 Likes
6

(Personal background: I have coded addons in the pre-extension era. I have never coded an extension.)

To address this point directly:

To this point above, i just offer some observations to the basic steps, found here:

https://docs.blender.org/manual/en/latest/advanced/extensions/getting_started.html

*Creating an extension takes only a few steps:

  1. Open the directory containing the add-on code or theme file.*

Open the directory, where? I’m guessing: In windows, just navigate to the folder where I’ve got the code.py file? It’s saved in c/desktop/addon stuff… ok, so I’ll go there.

  1. Add a blender_manifest.toml etc etc

For the most part, this step is clear. However, i’ll note that the order of variables in the Manifest table is not the same order of variables in the REQUIRED table. Example: Schema version is at the top / in the middle. “Internal version of the file format - use 1.0.0.” What is a ‘schema version’ ? What file format? Is every extension always to use 1.0.0, no matter what?

It did take multiple reads to understand that SCHEMA VERSION and VERSION are not the same thing.

3. Use the Blender command-line tool to build the extension .zip file.

A link is given for Blender command-line tool, but neither the link nor the preceeding tell me where to find/open/use the Blender command-line tool. There’s not even a screenshot of this tool, to let me know what I’m looking for. When i googled “Blender command-line tool” , i got:

https://docs.blender.org/manual/en/latest/advanced/command_line/index.html

Which tells me about the console messages. Eventually, I’m sort of using Blues Clues to work out that I need to launch a DOS command window in the blender directory, and that’s where I’ll be typing various ‘build extension’ commands… I think.

Now, certainly a few dozen people have figured all the above out - as, I do see lots of extensions on the website. But as this discussion is targeting towards new extension contributors, the above is just a bit of feedback on how the communication/guidelines could be improved to be a bit more clear and obvious.

Or to state it differently, more language written for people who have never done it before… vs people who are as well versed in coding, as the authors of the instructions are.

4 Likes
7

Definitively something to look at, then. An alternative is to add the folder to Scripting directories if it works.

8

I think it should work to add a Local Repository, enable Custom Directory and set Source to System.

1 Like
9

To this point above, i just offer some observations to the basic steps, found here (…)

Thanks for the feedback on the documentation.

1 Like
10

EDIT: after some discussion I’ve changed my mind on this topic, the previous add-on template no longer works without creating multiple files, so a way to create extensions with the new system seems reasonable.

While we can always have ways to streamline creating extensions, I worry the direction being proposed is encouraging “Blender as an IDE” (based on: creating extensions from Blender, then TOML syntax highlighting).

Users might expect to be able to build, develop & publish extensions from within Blender.
That can work in some simple use-cases, but I think extension-authors are likely to become frustrated, and us having the burden of maintaining development tools in Blender.

An alternative could be to make the extension-creation-tool command-line only,
since extension developers will need to use the command line to build the extension anyway.

For themes and potentially (keymaps/assets) a GUI tool makes more sense though.

From my own experience creating packages in other systems, the problems I run into are similar to the issues noted by @thorn-neverwake.

2 Likes
11

This seems to be working well, way more elegant than any of the alternatives.

So much so that I wonder about making this a bit less obscure of a feature. When adding a Local Repository there could be an enum prop to pick between a User or System repository.

Otherwise there are two extra step needed after adding them: change the type, and refresh local.

12

Could even have Add Development Repository under the (+) button, which would just be one with custom directory enabled, System source and name “Development”.

I guess the new operator to create an extension could also optionally add such a repository to the preferences.

13

I use local repo with custom path, but don’t point the source to system. What is the benefit of system?

I treat custom local repo as “Script Directory” from previous versions. Having them in completely custom path allows me to quickly test extensions in multiple versions of Blender, porting stuff between versions is easier when new ones come out, and you have always only one directory.

I think since most developers are developing for multiple Blender versions at once, the best option would be to let them pick a location anywhere in the system, so that when they update to newer version and import config from previous repo path doesnt’ change or gets duplicated.

14

Could even have Add Development Repository under the (+) button, which would just be one with custom directory enabled, System source and name “Development”.

That could be. It may be better than making the Add Local Repository more confusing.

Maybe we enable this only when Developers Extra is enabled?

I guess the new operator to create an extension could also optionally add such a repository to the preferences.

Totally.

15

The extensions installed in the (USER) local repository can be uninstalled. The ones in the System directory cannot (to prevent you uninstalling it and removing your precious code).

Maybe we enable this only when Developers Extra is enabled?

Just briefly talked with Brecht about it. Apparently the UI team is slowly making this option less used in Blender. If this is the case, we may as well always have this option, regardless of Developers Extra.

16

So add-ons will be in the system repo and symlinked to somewhere else? I got confused now.

This is the setup I have for reference (Windows):

  • Both my installation and config (appdata stuff) are on C drive
  • On D drive I have my “Development” folder with add-on repos
  • Also on D drive I have folder set-up called “Extensions” where I symlink all the stuff from “Development” folder, and in Blender I have custom local repo added that points to “Extensions” folder.

I have tested installing/uninstalling extensions when I set the system up. When I uninstall something symlink is removed from “Extensions” folder, but folder in “Development” stays.

Benefits of that:

  • I test installing/uninstalling extensions
  • When I set this system in 4.2 it was copied in 4.3 and upwards, so now when I want to test how something works in other versions I just open that version and test. No need to set up anything.
  • When I uninstall something it’s uninstalled in all Blender versions.

From what I’ve seen on the platform almost everyone except 2 or 3 people develop for multiple Blender versions. I unsuccessfully tried to convince some to limit min versions but they’re willing to go length and support. Having stuff tied in the version installation folder, and not shared by default will be a hard sell for users imo.

17

So add-ons will be in the system repo and symlinked to somewhere else? I got confused now.

There is no symlinking involved.

  1. “Add Development Repository”, “use_custom_folder” is on by default, all you need is to set Custom Folder to point to your source code folder (the manifest file is expected to be in a sub-folder).

  2. Enable the add-on.

We could even have the “Add Development Repository” to simply open a file browser and you pick the folder. But not sure if it is worth this behaving so different than the other repositories.

By the way I updated the meeting notes to suggest a SYSTEM repository instead of symlink.

18

That’s simpler, but why I would prefer symlink path (besides the three points I mentioned) is that I set up an add-on folder structure similar to how Campbell did it for community extensions. Actual add-on files and manifest that Blender expects is inside the source subfolder, and stuff like gitignore, README, .github, docs and etc are outside. This makes stuff like building much easier, except that Blender doesn’t read those add-ons anymore because it really really wants manifest and init to be in the add-on folder, and not inside add-on/source like I have. Symlink solves this.

I don’t feel too strongly about this, but I think if we’re doing set-up operators might as well try to instill good practices in terms of repo management and multi-version development, rather than leaving it as something uses discover much later and then they have to reorganize everything.

1 Like
19

I have only developed add-ons so far, not extensions, but my method for developing multi-file add-ons (as opposed to single file add-ons which can be run from the text editor) seems to be what is being suggested here with the use of Script Directories. I don’t know how relevant this is to the discussion but I thought I would explain my method, which I think works very well, just for some context for how some developers might be currently doing it. (I am using Windows.)

I have a separate folder for each add-on I develop and add a Script Directory in Blender’s Preferences for each of the add-ons, pointing to the add-on folder within that folder. E.g. for this add-on:

My New Add-on
├─ My New Add-on Code
|  └─ addons
|     └─ my_addon      #(git repository)
|        ├─ init.py
|        └─ etc.
├─ User Guide
├─ Marketplace Graphics
└─ Research

The Script Directory I add in Blender is the add-on ‘Code’ folder:

Name: Path:
My New Add-on …etc.\etc.\My New Add-on Code\

This has the benefits of:

  1. Not having to have have add-ons I am developing hidden away in Blender’s script directories.
  2. Not having to do anything with symlinks.
  3. Being able to have more complex folder structures without worrying about how Blender might interact with them (as the add-on code is just one part of making a publicly sellable product, along with user guides, marketing materials, research etc.)
  4. Easily reloadable using ‘Reload Scripts’.
20

Symlinks as a concept is not familiar to most users, especially on Windows. And personally I’ve also made mistakes when using them for various reasons in the past, it’s easy to forget how you set things up when you come back some months later.

For that reason I think it’s not good to recommend it in basic setup instructions, but it could be in more advanced instructions. Though personally my next step would be to add a Makefile, rather than a symlink.

The other part of your workflow is using the same repo to test install and uninstall of the extension. The problem is that when you uninstall, the symlink has to be recreated. If it was a one thing setup thing that people could blindly follow that would be better. But if the link breaks often during development, people are going to get confused, and possibly give up and just copy the folder with bad consequences.

The development repository would not be per version.