Breaking shader node changes for 4.0 #96219

New Issue

There are a number of proposed changes to shader nodes that break the Python API, mainly for add-ons that import and export shaders.

We need to make a decision to either:

Make these breaking changes in 3.2 or 3.3, and then do them all together with good communication so scripts only need to be updated once.
Postpone all breaking changes to 4.0, and see which parts of these patches can be non-breaking. For example we could have new general Mix/Combine/Separate nodes in addition to the existing ones.

Patches:

There are a number of proposed changes to shader nodes that break the Python API, mainly for add-ons that import and export shaders. We need to make a decision to either: * Make these breaking changes in 3.2 or 3.3, and then do them all together with good communication so scripts only need to be updated once. * Postpone all breaking changes to 4.0, and see which parts of these patches can be non-breaking. For example we could have new general Mix/Combine/Separate nodes in addition to the existing ones. Patches: * [ ] [D14034: Geometry/Compositor/Shader/Texture Nodes: Add general Combine/Separate Color nodes](https://archive.blender.org/developer/D14034) * [ ] [D14257: Shader Nodes: Changes to node UI and default values to improve consistency](https://archive.blender.org/developer/D14257) * [ ] [D14202: UI (Shader/Compositor): Rename "RGB" input to "Color" input](https://archive.blender.org/developer/D14202) * [ ] [D13749: Node: Mix node](https://archive.blender.org/developer/D13749) * [ ] [D13359: Rename "fac" to "factor" across all nodes](https://archive.blender.org/developer/D13359) * [ ] Use proper "Brightness" word in names

Changed status from 'Needs Triage' to: 'Confirmed'

Added subscriber: @brecht

Gathering feedback on devtalk here:
https://devtalk.blender.org/t/feedback-on-breaking-python-api-changes-for-shader-nodes/23281

Gathering feedback on devtalk here: https://devtalk.blender.org/t/feedback-on-breaking-python-api-changes-for-shader-nodes/23281

Added subscriber: @MysteryPancake

Is there any way the Python API could be detoured to avoid breaking changes? E.g. "Fac" in the API aliased to "Factor"?

It would be a shame to have more duplicate code for Mix/Combine/Separate nodes

Is there any way the Python API could be detoured to avoid breaking changes? E.g. "Fac" in the API aliased to "Factor"? It would be a shame to have more duplicate code for Mix/Combine/Separate nodes

Added subscriber: @EAW

Added subscriber: @Diogo_Valadares

The problem is that some scripts use .name instead of the .identifier, and worse, that node.inputs["Factor"]" actually use the name instead of the identifier currently.

The problem is that some scripts use `.name` instead of the `.identifier`, and worse, that `node.inputs["Factor"]"` actually use the name instead of the identifier currently.

Added subscriber: @Aeraglyx

Added subscribers: @Ethan-Hall, @HooglyBoogly, @fclem, @CharlieJolly

@CharlieJolly, @HooglyBoogly, @MysteryPancake, @Ethan-Hall, @fclem

I propose we do the following:

For Blender 3.2, add new Mix and Combine/Separate nodes and convert existing nodes in .blend files. Keep the old nodes available in the Python API but hidden from the menus.
Postpone other changes to another release where we make more breaking changes to shader nodes that. For example in the context of new textures nodes or improvements to the principled BSDF, that are likely to happen before 4.0.

That's rather conservative, but I think it's worth taking API compatibility a bit more seriously.

@CharlieJolly, @HooglyBoogly, @MysteryPancake, @Ethan-Hall, @fclem I propose we do the following: * For Blender 3.2, add new Mix and Combine/Separate nodes and convert existing nodes in .blend files. Keep the old nodes available in the Python API but hidden from the menus. * Postpone other changes to another release where we make more breaking changes to shader nodes that. For example in the context of new textures nodes or improvements to the principled BSDF, that are likely to happen before 4.0. That's rather conservative, but I think it's worth taking API compatibility a bit more seriously.

Adding a few more patches here for consideration

WIP: Separate ColorRamp node name into Color Ramp #104996
WIP: Rename Bright/Contrast to Brightness Contrast #104998
WIP: Rename Dilate/Erode to Dilate Erode #104999

There needs to be a consensus of the use or not use of the "/" separator. I'm not sure about it myself but the inconsistency bothers me.

Adding a few more patches here for consideration [WIP: Separate ColorRamp node name into Color Ramp #104996](https://projects.blender.org/blender/blender/pulls/104996) [WIP: Rename Bright/Contrast to Brightness Contrast #104998](https://projects.blender.org/blender/blender/pulls/104998) [WIP: Rename Dilate/Erode to Dilate Erode #104999](https://projects.blender.org/blender/blender/pulls/104999) There needs to be a consensus of the use or not use of the "/" separator. I'm not sure about it myself but the inconsistency bothers me.

Changing UI names like these does not break file or API compatibility. If the names are similar enough to the previous ones and not break documentation completely, we can do them any time.

Ah, I gave the opposite advice in #104996, since the node names are used by the Python API and the default names would change. But if that's considered an okay change, I think these names are much better, so I'd support the changes @zanqdo proposed.

The socket names are used in the API, but the node names are not I think.

The socket names are used in the API, but the node names are not I think.

Yeah, that's why I didn't change the Bright socket name. I guess that one is a change for 4.0

> The socket names are used in the API, but the node names are not I think. Yeah, that's why I didn't change the *Bright* socket name. I guess that one is a change for 4.0

Created a WIP PR for the Brightness rename #108128

Can we add it to the list?

I might need help on do-versioning.

Created a WIP PR for the Brightness rename https://projects.blender.org/blender/blender/pulls/108128 Can we add it to the list? I might need help on do-versioning.

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Breaking shader node changes for 4.0 #96219