Property Groups

Blender has two concepts for custom data: Properties and IDData

ID data can be arbitrary Python values, but come with restrictions that make building UI from them difficult. Thus we use Properties which come with their own restrictions.

What are PropertyGroups?

PropertyGroups are the way to emulate any kind of dict/struct in Blender's Property class system. This means they are the way we emulate Component values from Bevy.

# Example from Blender docs
import bpy

class MyPropertyGroup(bpy.types.PropertyGroup):
    custom_1: bpy.props.FloatProperty(name="My Float")
    custom_2: bpy.props.IntProperty(name="My Int")


bpy.utils.register_class(MyPropertyGroup)

bpy.types.Object.my_prop_grp = bpy.props.PointerProperty(type=MyPropertyGroup)

# test this worked
bpy.data.objects[0].my_prop_grp.custom_1 = 22.0

Properties on Objects

Properties can be attached to a number of different objects as "static" types, including the WindowManager, Scene, Object, Mesh, or Material. This results in every element of that type having an initialized value of the corresponding type.

Here's an example of setting a selected_component field on the type of WindowManager. Roughly speaking: bpy.types is the type, and bpy.props are values. This is critically important when setting new fields on types.

bpy.types.WindowManager.selected_component = bpy.props.StringProperty(
    name="component type path",
    description="The component that will be added if selected",
    update=on_select_new_component,
)

Library Overrides

Components can be set on Blender Objects in Blender Collections that are used as Blender Assets. These assets can be instanced into another Blender Scene and the Component PropertyGroup values (or other data) can be overridden using Library Overrides.

It is critically important that every item in the entire hierarchy of Properties includes the override={"LIBRARY_OVERRIDABLE"} field. If this detail is not maintained across the entire hierarchy, then values overridden on Component PropertyGroup fields for instanced assets can behave erratically, such as being capable of being modified but not actually saved into a .blend file.